build: Only deploy docs for latest tag

.github/workflows/docs.yml

@@ -1,16 +1,19 @@
 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:
+  build:
+    name: Build documentation (and deploy for git tag)
     runs-on: ubuntu-latest
     permissions:
       contents: write
@@ -33,13 +36,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 `make html` from the terminal to generate PyDRex's documentation
+(available in the `html` directory), including the API reference.
 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 or MacOS 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