build: Only deploy docs for latest tag

This brings us one step towards having docs for every tagged version.
For now (after the next tag push) there should only be one website for
the latest tagged version. Earlier versions can be built offline.
Progress to #199.

In any case, it is better than the current situation: html documentation
is being deployed for every single push on `main`, and the docs website
did not indicate a version number anywhere. With these GH workflow
adjustments, the docs should still be _built_ for each PR/push to main,
allowing to catch errors in the documentation setup as they arise,
but the html pages will not deployed to GitHub Pages if there is no tag.
The version (obtained from `git describe`) is also indicated clearly
on the website landing page and in the API docs sidebar footer.

Related things that I rolled in here:
- new make target to build docs (simply `make html` in the action spec)
- favicon and proper branding (multiple resolutions of logo)
- removed a duplicated sentence from the README
- `docs/template/README.md` to explain how to maintain the template
- fixed `rm -r` -> `rm -rf` in `make clean` recipe

.github/workflows/docs.yml

@@ -1,13 +1,15 @@
 name: GitHub Pages
 
-on:
+on:  # Always attempt html build on push & PR, but only deploy when there is a new tag.
   push:
     branches:
       - main
+    tags:
+      - v*
   pull_request:
     branches:
       - main
-  workflow_dispatch:
+  workflow_dispatch:  # Allows to manually trigger the job from the web UI.
 
 jobs:
   deploy:
@@ -33,13 +35,10 @@ jobs:
           python3 -m venv .venv-gh-pages
           source .venv-gh-pages/bin/activate
           python3 -m pip install "$PWD"[doc,test]
-          pdoc -t docs/template -o html --math pydrex !pydrex.mesh !pydrex.distributed tests
+          make html
       - name: Deploy
         uses: peaceiris/actions-gh-pages@v4
-        # If you're changing the branch from main,
-        # also change the `main` in `refs/heads/main`
-        # below accordingly.
-        if: ${{ github.ref == 'refs/heads/main' }}
+        if: ${{ startsWith(github.ref, 'refs/tags/' }}
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           publish_dir: ./html

Makefile

@@ -1,7 +1,9 @@
 .SHELLFLAGS += -u
 .ONESHELL:
 MAKEFLAGS += --no-builtin-rules
+VERSION = $(shell git describe)
 
+# NOTE: Keep this at the top! Bare `make` should just build the sdist + bdist.
 dist:
 	python -m build
 
@@ -12,8 +14,15 @@ test:
 	mkdir out
 	pytest -v --outdir=out
 
+html:
+	2>pdoc.log pdoc -t docs/template -o html pydrex !pydrex.mesh !pydrex.distributed tests \
+		--favicon "https://raw.githubusercontent.com/seismic-anisotropy/PyDRex/main/docs/assets/favicon32.png" \
+		--footer-text "PyDRex $(VERSION)"
+
 clean:
-	rm -r dist
-	rm -r out
+	rm -rf dist
+	rm -rf out
+	rm -rf html
+	rm -rf pdoc.log
 
 .PHONY: release test clean

README.md

@@ -1,7 +1,7 @@
 # PyDRex
 
-<p align="center" style="margin:4%;">
-    <img alt="PyDRex logo" src="https://raw.githubusercontent.com/seismic-anisotropy/PyDRex/main/docs/assets/pydrex.png" width="25%"/>
+<p align="center" style="margin:50px;">
+    <img alt="PyDRex logo" src="https://raw.githubusercontent.com/seismic-anisotropy/PyDRex/main/docs/assets/logo265.png">
 </p>
 
 #### Simulate crystallographic preferred orientation evolution in polycrystals
@@ -45,34 +45,27 @@ declared in the `pyproject.toml` file.
 ## Testing
 
 Running tests or examples requires a local git clone or unpacked source distribution.
+Install test suite dependencies with `pip install '.[test]'`.
 
 Some tests can optionally output figures or extended diagnostics when run locally.
-Testing locally requires a local git clone or source distribution of PyDRex.
 Check the `tests/README.md` file for details.
 
 Further examples that demonstrate how PyDRex can be used within geodynamic
-simulations are provided in the `examples` folder.
+simulations are provided in subfolders of the `examples` folder.
 They have their own README file as well.
 
 ## Building offline documentation
 
-The documentation can be built offline using [pdoc](https://github.com/mitmproxy/pdoc),
-with the command:
+The documentation can be built offline from a git clone or source distribution.
+Install documentation builder dependencies with `pip install '.[doc]'`.
 
-    pdoc -t docs/template -o html --math pydrex tests
-
-which will output the html documentation into a folder called `html`.
+Run the make command `make html` which will output the documentation,
+including the generated API reference, into a folder called `html`.
 The homepage will be `html/index.html`.
-Note that some submodules depend on optional dependencies,
-and should otherwise be excluded:
-
-    pdoc -t docs/template -o html --math pydrex !pydrex.mesh !pydrex.distributed tests
-
-See also the provided [GitHub actions workflow](https://raw.githubusercontent.com/seismic-anisotropy/PyDRex/main/.github/workflows/docs.yml).
 
 ## Contributing
 
-For a development environment, clone the [source code](https://github.com/seismic-anisotropy/PyDRex)
+For a Linux development environment, clone the [source code](https://github.com/seismic-anisotropy/PyDRex)
 and execute the Bash script `tools/venv_install.sh`.
 This will set up a local Python virtual environment with an [editable install](https://setuptools.pypa.io/en/latest/userguide/development_mode.html)
 of PyDRex that can be activated/deactivated by following the displayed prompts.

docs/template/README.md

@@ -0,0 +1,14 @@
+The docs template is modified from the default template found at:
+
+<https://github.com/mitmproxy/pdoc/tree/main/pdoc/templates/default>
+
+The most significant changes are:
+- adding buttons to chose from API or tests/examples docs to the landing page
+- switching to a dark CSS theme, based on the example found at the link below
+
+<https://github.com/mitmproxy/pdoc/tree/main/examples/dark-mode>
+
+When pdoc releases a new version we should check
+if there were any upstream template/theme changes that we want to merge.
+It is not necessary to copy-paste template files that we don't intend to change,
+as pdoc will automatically fall back to using the files from the default theme.

docs/template/index.html.jinja2

@@ -3,8 +3,8 @@
 {% block title %}PyDRex: Welcome{% endblock %}
 
 {% block nav %}
-    <img src="https://raw.githubusercontent.com/seismic-anisotropy/PyDRex/main/docs/assets/pydrex.png" class="logo" alt="project logo"/>
-    <h4>PyDRex</h4>
+    <img src="https://raw.githubusercontent.com/seismic-anisotropy/PyDRex/main/docs/assets/logo160.png" class="logo" alt="project logo"/>
+    <h4>{{ footer_text }}</h4>
     <br>
     <input type="search" placeholder="Search..." role="searchbox" aria-label="search" pattern=".+" required>
 {% endblock %}

tests/README.md

@@ -1,7 +1,9 @@
 # PyDRex tests
 
-Running the tests requires [pytest](https://docs.pytest.org), and up to ~16GB RAM.
-From the root of the source tree, run `pytest`.
+Running the base test suite requires [pytest](https://docs.pytest.org), and up to ~16GB RAM.
+By default, `make test` will attempt to write persistent logs and output to `./out/`.
+
+Alternatively, run `pytest` from the root of the source tree.
 To print more verbose information (including INFO level logging),
 such as detailed test progress, use the flag `pytest -v`.
 The custom optional flag `--outdir="OUT"` is recommended