Merge pull request #191 from mabarnes/docs-build-update

Improve README for building docs, and fix pdf build

.github/workflows/documentation.yml

@@ -22,3 +22,16 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # Authenticate with GitHub Actions token
         run: julia --project=docs/ docs/make.jl
+
+  build-pdf:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: julia-actions/setup-julia@latest
+        with:
+          version: '1.10'
+      - name: Install dependencies
+        run: |
+          pip3 install --user matplotlib
+      - name: Build and deploy
+        run: julia --project=docs/ docs/make-pdf.jl

docs/Project.toml

@@ -1,5 +1,6 @@
 [deps]
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+Glob = "c27321d9-0574-5035-807b-f59d2c89b15c"
 Revise = "295af30f-e4ad-537b-8983-00126c2a3abe"
 makie_post_processing = "4dd1b173-c370-4c56-9cc2-d797e41ae9f0"
 moment_kinetics = "b5ff72cc-06fc-4161-ad14-dba1c22ed34e"

docs/README.md

@@ -3,10 +3,16 @@
 
 The docs are built automatically when a pull request is merged into the `master` branch on `github.com/mabarnes/moment_kinetics`. 
 
-To build a local version, run `julia --project make.jl` in this directory. To see the output, open `build/index.html` with a web browser.
+To build a local version, run `julia --project make.jl` in this directory. To see the output, open `build/index.html` with a web browser. It may be necessary when editing the doc pages to rebuild many times. Then it is more convenient to keep a REPL session open from `julia --project` and just keep running `julia> include("make.jl")` as this avoids repeated compilation of code.
+
+It is also possible to build a pdf version of the documentation by replacing `make.jl` with `make-pdf.jl`. This requires LuaTex to be installed e.g. on Ubuntu or Mint
+```
+sudo apt install texlive-luatex
+```
+It may also need the `texlive-latex-extra` [JTO already had this installed, so hasn't tested without it].
 
 The docs are built using [Documenter.jl](https://juliadocs.github.io/Documenter.jl/stable/).
 
-The docs are written in Markdown, in files in the `docs/src/` subdirectory. `index.md` contains the home page and contents, and there is a file for each module (with `docs/src/foo.md` corresponding to the module defined in `src/foo.jl`). Each module page contains at minimum the docs auto-generated from the docstrings in the Julia source code - additional content can be added in the `*.md` files as needed. For extended syntax for documenting Julia code, and including LaTeX-syntax expressions, see the [Documenter.jl online documentation](https://juliadocs.github.io/Documenter.jl/stable/).
+The docs are written in Markdown, in files in the `docs/src/` subdirectory. `index.md` contains the home page and contents, there are several hand-written documentation pages `docs/src/input_options.md`, etc., and there is a file for each module (with `docs/src/zz_foo.md` corresponding to the module defined in `src/foo.jl`). Each module page contains at minimum the docs auto-generated from the docstrings in the Julia source code - additional content can be added in the `*.md` files as needed. The `zz_` prefix for the module pages is so that the pages are ordered nicely in the sidebar of the docs - in the sidebar the entries are ordered by filename, so using the `zz_` prefix for module pages ensures they are found together below the hand-written pages. For extended syntax for documenting Julia code, and including LaTeX-syntax expressions, see the [Documenter.jl online documentation](https://juliadocs.github.io/Documenter.jl/stable/).
 
 Docstrings should be formatted following the [guidelines for Julia documentation](https://docs.julialang.org/en/v1/manual/documentation/#man-documentation).

docs/make-pdf.jl

@@ -9,13 +9,33 @@ It may also need the `texlive-latex-extra` [JTO: already had this installed, so
 tested without it].
 """
 
+using Pkg
+
+repo_dir = dirname(dirname(@__FILE__))
+Pkg.develop([PackageSpec(path=joinpath(repo_dir, "moment_kinetics")),
+             PackageSpec(path=joinpath(repo_dir, "makie_post_processing", "makie_post_processing")),
+             PackageSpec(path=joinpath(repo_dir, "plots_post_processing", "plots_post_processing"))])
+Pkg.instantiate()
+
 using Documenter
-using moment_kinetics
+using Glob
+using moment_kinetics, makie_post_processing, plots_post_processing
+
+doc_files = glob("src/*.md")
+
+# Remove the src/ prefix
+doc_files = [basename(s) for s ∈ doc_files]
+
+if get(ENV, "CI", nothing) == "true"
+    latex_kwargs = (platform = "docker",)
+else
+    latex_kwargs = ()
+end
 
 makedocs(
     sitename = "momentkinetics",
-    format = Documenter.LaTeX(),
-    modules = [moment_kinetics],
+    format = Documenter.LaTeX(; latex_kwargs...),
+    modules = [moment_kinetics, makie_post_processing, plots_post_processing],
     authors = "M. Barnes, J.T. Omotani, M. Hardman",
-    pages = ["moment_kinetic_equations.md"]
+    pages = doc_files
 )