Structure reference in docs in sections (#134)

* structure reference in docs in sections some other fixes and small additions to the docs * add docs preview in PRs in development section * fix Pages in refs (explicitly list all files) * fix missing quotation marks * fix typos * Update src/DispersiveShallowWater.jl Co-authored-by: Hendrik Ranocha <[email protected]> * spelling * add reference to Svärd-Kalisch equations * try again to list equation files automatically * list files explicitly again * rename SGN file * add hyphens in summation-by-parts operators * Update docs/src/ref.md Co-authored-by: Hendrik Ranocha <[email protected]> * remove indendation for consistency * dynamically set all files in equations and callbacks_step in reference * fix * Apply suggestions from code review Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Hendrik Ranocha <[email protected]> * try macos-latest instead of macos-13 to debug CI * lower tolerance --------- Co-authored-by: Hendrik Ranocha <[email protected]> Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
JoshuaLampert · Aug 17, 2024 · 8fcba88 · 8fcba88
1 parent 716f27c
commit 8fcba88
Show file tree

Hide file tree

Showing 14 changed files with 224 additions and 37 deletions.
diff --git a/.github/workflows/CI.yml b/.github/workflows/CI.yml
@@ -47,7 +47,7 @@ jobs:
           - '1.9'
         os:
           - ubuntu-latest
-          - macos-13
+          - macos-latest
           - windows-latest
         arch:
           - x64

diff --git a/.github/workflows/DocPreviewCleanup.yml b/.github/workflows/DocPreviewCleanup.yml
@@ -0,0 +1,33 @@
+name: Doc Preview Cleanup
+
+on:
+  pull_request:
+    types: [closed]
+
+# Ensure that only one "Doc Preview Cleanup" workflow is force pushing at a time
+concurrency:
+  group: doc-preview-cleanup
+  cancel-in-progress: false
+
+jobs:
+  doc-preview-cleanup:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout gh-pages branch
+        uses: actions/checkout@v4
+        with:
+          ref: gh-pages
+      - name: Delete preview and history + push changes
+        run: |
+          if [ -d "${preview_dir}" ]; then
+              git config user.name "Documenter.jl"
+              git config user.email "[email protected]"
+              git rm -rf "${preview_dir}"
+              git commit -m "delete preview"
+              git branch gh-pages-new $(echo "delete history" | git commit-tree HEAD^{tree})
+              git push --force origin gh-pages-new:gh-pages
+          fi
+        env:
+          preview_dir: previews/PR${{ github.event.number }}
diff --git a/README.md b/README.md
@@ -16,8 +16,8 @@ To date, it provides provably conservative, entropy-conserving and well-balanced
 * the [dispersive shallow water model proposed by Magnus Svärd and Henrik Kalisch](https://arxiv.org/abs/2302.09924),
 * the [Serre-Green-Naghdi equations](https://arxiv.org/abs/2408.02665).
 
-The semidiscretizations are based on summation by parts (SBP) operators, which are implemented in [SummationByPartsOperators.jl](https://github.com/ranocha/SummationByPartsOperators.jl/).
-In order to obtain fully discrete schemes, the time integration methods from [OrdinaryDiffEq.jl](https://github.com/SciML/OrdinaryDiffEq.jl) are used to solve the resulting ordinary differential equations.
+The semidiscretizations are based on summation-by-parts (SBP) operators, which are implemented in [SummationByPartsOperators.jl](https://github.com/ranocha/SummationByPartsOperators.jl/).
+To obtain fully discrete schemes, the time integration methods from [OrdinaryDiffEq.jl](https://github.com/SciML/OrdinaryDiffEq.jl) are used to solve the resulting ordinary differential equations.
 Fully discrete entropy-conservative methods can be obtained by using the [relaxation method](https://epubs.siam.org/doi/10.1137/19M1263662) provided by DispersiveShallowWater.jl.
 A more detailed documentation can be found [online](https://JoshuaLampert.github.io./DispersiveShallowWater.jl/stable/).
 

diff --git a/docs/make.jl b/docs/make.jl
@@ -2,6 +2,31 @@ using Documenter
 using DispersiveShallowWater
 using TrixiBase
 
+# Dynamically replace all files in subdirectories of the source directory to include all files in these subdirectories
+# This way they don't need to be listed explicitly
+EQUATIONS_FILES_TO_BE_INSERTED = joinpath.(Ref("equations"),
+                                           readdir(joinpath(dirname(@__DIR__), "src",
+                                                            "equations")))
+CALLBACKS_STEP_FILES_TO_BE_INSERTED = joinpath.(Ref("callbacks_step"),
+                                                readdir(joinpath(dirname(@__DIR__), "src",
+                                                                 "callbacks_step")))
+
+ref_path = joinpath(@__DIR__, "src", "ref.md")
+lines = readlines(ref_path)
+open(ref_path, "w") do io
+    for line in lines
+        if contains(line, "EQUATIONS_FILES_TO_BE_INSERTED")
+            line = replace(line,
+                           "EQUATIONS_FILES_TO_BE_INSERTED" => EQUATIONS_FILES_TO_BE_INSERTED)
+        end
+        if contains(line, "CALLBACKS_STEP_FILES_TO_BE_INSERTED")
+            line = replace(line,
+                           "CALLBACKS_STEP_FILES_TO_BE_INSERTED" => CALLBACKS_STEP_FILES_TO_BE_INSERTED)
+        end
+        println(io, line)
+    end
+end
+
 # Define module-wide setups such that the respective modules are available in doctests
 DocMeta.setdocmeta!(DispersiveShallowWater, :DocTestSetup, :(using DispersiveShallowWater);
                     recursive = true)
@@ -32,4 +57,5 @@ makedocs(;
 
 deploydocs(;
            repo = "github.com/JoshuaLampert/DispersiveShallowWater.jl",
-           devbranch = "main")
+           devbranch = "main",
+           push_preview = true)
diff --git a/docs/src/development.md b/docs/src/development.md
@@ -48,3 +48,6 @@ julia --project=docs --color=yes docs/make.jl
 ```
 
 The resulting `.html` files can then be found in `docs/build/` and you can look at them by opening them in a browser.
+For pull requests from the main repository (i.e. not from a fork), the documentation is automatically built and can
+be previewed under `https://joshualampert.github.io/DispersiveShallowWater.jl/previews/PRXXX/` where `XXX` is the number
+of the pull request.
diff --git a/docs/src/index.md b/docs/src/index.md
@@ -10,13 +10,14 @@
 [![DOI](https://zenodo.org/badge/635090135.svg)](https://zenodo.org/doi/10.5281/zenodo.10034636)
 
 [**DispersiveShallowWater.jl**](https://github.com/JoshuaLampert/DispersiveShallowWater.jl) is a [Julia](https://julialang.org/) package that implements structure-preserving numerical methods for dispersive shallow water models.
-To date, it provides provably conservative, entropy-conserving and well-balanced numerical schemes for two dispersive shallow water models:
+To date, it provides provably conservative, entropy-conserving and well-balanced numerical schemes for some dispersive shallow water models:
 
 * the [BBM-BBM equations with varying bottom topography](https://iopscience.iop.org/article/10.1088/1361-6544/ac3c29),
-* the [dispersive shallow water model proposed by Magnus Svärd and Henrik Kalisch](https://arxiv.org/abs/2302.09924).
+* the [dispersive shallow water model proposed by Magnus Svärd and Henrik Kalisch](https://arxiv.org/abs/2302.09924),
+* the [Serre-Green-Naghdi equations](https://arxiv.org/abs/2408.02665).
 
-The semidiscretizations are based on summation by parts (SBP) operators, which are implemented in [SummationByPartsOperators.jl](https://github.com/ranocha/SummationByPartsOperators.jl/).
-In order to obtain fully discrete schemes, the time integration methods from [OrdinaryDiffEq.jl](https://github.com/SciML/OrdinaryDiffEq.jl) are used to solve the resulting ordinary differential equations.
+The semidiscretizations are based on summation-by-parts (SBP) operators, which are implemented in [SummationByPartsOperators.jl](https://github.com/ranocha/SummationByPartsOperators.jl/).
+To obtain fully discrete schemes, the time integration methods from [OrdinaryDiffEq.jl](https://github.com/SciML/OrdinaryDiffEq.jl) are used to solve the resulting ordinary differential equations.
 Fully discrete entropy-conservative methods can be obtained by using the [relaxation method](https://epubs.siam.org/doi/10.1137/19M1263662) provided by DispersiveShallowWater.jl.
 
 ## Installation