[WIP] Generate C/Fortran API docs with Doxygen (#52)

* Generate C/Fortran API docs with Doxygen * complete documentation of trixi.c and trixi.f90 * Build & deploy doxygen docs * Use GITHUB_TOKEN for doxygen deployment * Fix some links and descriptions * Use deploy key for doxygen * adapt user hint * Update utils/libtrixi-init-julia * Make doxygen builds respect Documenter.jl versioning * Set environment variable for proper folder generation * Run workflow always when Documenter is run --------- Co-authored-by: Benedict Geihe <[email protected]> Co-authored-by: Benedict <[email protected]>
trixi-framework · Jul 13, 2023 · a5cea7b · a5cea7b
1 parent 5ba6bf2
commit a5cea7b
Show file tree

Hide file tree

Showing 15 changed files with 3,379 additions and 48 deletions.
diff --git a/.github/workflows/Documenter.yml b/.github/workflows/Documenter.yml
@@ -26,6 +26,8 @@ concurrency:
 jobs:
   build-docs:
     runs-on: ubuntu-latest
+    outputs:
+      doxygen_dir: ${{ steps.determine_doxygen_dir.outputs.doxygen_dir }}
     steps:
       - uses: actions/checkout@v3
       - uses: julia-actions/setup-julia@v1
@@ -45,3 +47,32 @@ jobs:
           DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }} # For authentication with SSH deploy key
           GKSwstype: 100 # To make GitHub Action work, disable showing a plot window with the GR backend of the Plots package
         run: julia --project=docs --color=yes docs/make.jl
+      - name: Determine folder for doxygen docs
+        id: determine_doxygen_dir
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # Required to determine directory
+        run: |
+          doxygen_dir=$(julia --project=docs --color=yes docs/determine_doxygen_dir.jl)
+          echo "doxygen_dir=$doxygen_dir"
+          echo "doxygen_dir=$doxygen_dir" >> "$GITHUB_OUTPUT"
+
+  build-doxygen:
+    runs-on: ubuntu-latest
+    needs: build-docs
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+      - name: Install doxygen
+        run: |
+          sudo apt-get install -y doxygen
+      - name: Build doxygen docs
+        run: |
+          cd docs/doxygen
+          doxygen
+      - name: Deploy doxygen docs
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          deploy_key: ${{ secrets.ACTIONS_DEPLOY_KEY }}
+          publish_dir: ./docs/doxygen/build/html
+          destination_dir: ${{ needs.build-docs.outputs.doxygen_dir }}
diff --git a/.gitignore b/.gitignore
@@ -14,8 +14,5 @@ cmake_install.cmake
 libtrixi.mod
 libtrixi.so*
 
-# Documenter
-docs/build
-
 # VS Code
 .vscode
diff --git a/LibTrixi.jl/src/api_c.jl b/LibTrixi.jl/src/api_c.jl
@@ -9,9 +9,9 @@ The libelixir has a similar purpose as a regular "elixir" in Trixi.jl, as it com
 defines a simulation setup in Julia code. A key difference (and thus the name libelixir) is
 that instead of running a simulation directly, it should define an argument-less function
 named `init_simstate()` that returns a [`SimulationState`](@ref) with the complete
-simulation setup. `trixi_initialize_simulation` will store the `SimulationState` object internally and
-allow one to use it in subsequent calls to libtrixi via the handle returned from this
-function.
+simulation setup. `trixi_initialize_simulation` will store the `SimulationState` object
+internally and allow one to use it in subsequent calls to libtrixi via the handle returned
+from this function.
 
 For convenience, when using LibTrixi.jl directly from Julia, one can also pass a regular
 `String` in the `libelixir` argument.

diff --git a/docs/determine_doxygen_dir.jl b/docs/determine_doxygen_dir.jl
@@ -0,0 +1,36 @@
+using Documenter
+
+# Note: If you change any input values here, make sure you also update the call to
+# deploydocs(...) in `make.jl`
+repo = "github.com/trixi-framework/libtrixi"
+devbranch = "main"
+push_preview = true
+
+# Internally used values for convenience
+branch = "gh-pages"
+branch_previews = branch
+devurl = "dev"
+repo_previews = repo
+tag_prefix = ""
+
+# Create a deploy configuration for GitHub Actions (we ignore other CI systems here)
+deploy_config = Documenter.GitHubActions();
+
+# Create a deploy decision using the same default values as are used in Documenter.jl's
+# implementation of `deploydocs(...)`
+# See also: https://github.com/JuliaDocs/Documenter.jl/blob/7c97a86a31e360d7d22082a9a783b0cab24163b5/src/deploydocs.jl#L213-L221
+deploy_decision = Documenter.deploy_folder(
+    deploy_config;
+    branch,
+    branch_previews,
+    devbranch,
+    devurl,
+    push_preview,
+    repo,
+    repo_previews,
+    tag_prefix,
+);
+
+# Print (to stdout) the folder name relative to repo root
+# Note: Warnings/info messages will be printed to stderr
+println(joinpath(deploy_decision.subfolder, "c-fortran-api"))