More documentation and visualisation fixes (#214)

* docs: Improve documentation and add simple <200LOC cornerflow example

* docs: Add output figure for cornerflow example

* fix: Fix voigt averaging to use new stiffness tensors API

* docs: Add PyPI and GitHub buttons to docs homepage and comment CSS file

* dev: Migrate from Makefile to justfile

The [just](https://github.com/casey/just) build command runner is "just"
a better `make`, for our purposes. In particular, it properly terminates
the documentation build if `setuptools-scm` is not installed. I'm sure
there is a way to cast spells at `make` to make it do that, but why?
Whenever there's a big .PHONY line in a Makefile, it means that `make`
is probably the wrong tool. Also, the old Makefile I provided was only
valid for GNU make (make portability is a bit gross).

Also, `just` has binaries built for every major platform so installing
is not a hassle.

* dev: Fix docs action to use just instead of make

* test: Remove alpha kwarg which is not supported by streamplot

* dev: Use github actions to setup just instead of relying on apt

* fix: Add enstatite CPO component to standalone example

* fix: Typo and wording

---------

Co-authored-by: Thomas Duvernay <[email protected]>

.github/workflows/docs.yml

@@ -29,14 +29,15 @@ jobs:
           python-version: '3.12'
 
       - name: Build
+        uses: extractions/setup-just@v1
         run: |
           sudo apt-get update
           sudo apt-get install -y python3-pip
           python3 -m pip install --upgrade pip
           python3 -m venv .venv-gh-pages
           source .venv-gh-pages/bin/activate
           python3 -m pip install "$PWD"[doc,test]
-          make html
+          just html
       - name: Deploy
         uses: peaceiris/actions-gh-pages@v4
         if: ${{ startsWith(github.ref, 'refs/tags/') }}

README.md

@@ -6,24 +6,25 @@
 
 #### Simulate crystallographic preferred orientation evolution in polycrystals
 
-This repository contains a Python 3 reimplementation of the D-Rex model
+PyDRex is a new Python 3 implementation of the D-Rex model
 for the evolution of crystallographic preferred orientation in polycrystals.
 The code is available for use under the [GNU GPL v3](https://www.gnu.org/licenses/gpl-3.0.en.html) license.
 Documentation is accessible via Python's REPL `help()` and also [online](https://seismic-anisotropy.github.io/PyDRex/).
 
 ## Installing
 
-Check `requires-python` in `pyproject.toml` for the minimum required Python
-version. The software is tested on Linux, MacOS and Windows, however large
-simulations require substantial computational resources usually afforded by HPC
-Linux clusters. Linux shell scripts for setting up a [Ray](https://www.ray.io/) cluster
+Tagged package versions can be installed from [PyPi](https://pypi.org/project/pydrex/).
+The minimum required Python version is displayed in the sidebar (search for `Requires: Python`).
+PyDRex is tested on Linux, MacOS and Windows,
+however large simulations require substantial computational resources
+usually only afforded by HPC Linux clusters.
+Linux shell scripts for setting up a [Ray](https://www.ray.io/) cluster
 on distributed memory PBS systems are provided in the `tools` folder.
 
 Optional mesh generation using [gmsh](https://pypi.org/project/gmsh/) is available,
 however the `gmsh` module requires the [`glu`](https://gitlab.freedesktop.org/mesa/glu) library
 (which may require manual installation on some systems).
 
-Tagged package versions can be installed from [PyPi](https://pypi.org/project/pydrex/).
 To install the latest version, execute:
 
     pip install pydrex
@@ -56,13 +57,15 @@ They have their own README file as well.
 
 ## Building offline documentation
 
-The documentation can be built offline from a git clone or source distribution.
+The documentation can be built offline from a git clone or unpacked source distribution.
 Install documentation builder dependencies with `pip install '.[doc]'`.
+Developers are also recommended to download the [just](https://github.com/casey/just) command runner.
+Otherwise, build commands can be found in the provided `justfile`.
 
-Run `make html` from the terminal to generate PyDRex's documentation
+Run `just 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`.
-Alternatively, run `make live_docs` to build and serve the documentation on a `localhost` port.
+Alternatively, run `just live_docs` to build and serve the documentation on a `localhost` port.
 Follow the displayed prompts to open the live documentation in a browser.
 It should automatically reload after changes to the source code.
 
@@ -72,3 +75,8 @@ For a Linux or MacOS development environment, clone the [source code](https://gi
 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.
+
+For documentation contributions, please note that
+only `h2` headings will be rendered within HTML anchor elements.
+Avoid using markdown headings with 3 or more leading hashes in most cases,
+as these will not appear in the documentation sidebar nor be linkable.

docs/template/index.html.jinja2

@@ -4,9 +4,11 @@
 
 {% block nav %}
     <img src="https://raw.githubusercontent.com/seismic-anisotropy/PyDRex/main/docs/assets/logo160.png" class="logo" alt="project logo"/>
-    <h4>{{ footer_text }}</h4>
-    <br>
+    <div>
     <input type="search" placeholder="Search..." role="searchbox" aria-label="search" pattern=".+" required>
+    <br>
+    <h6>{{ footer_text }}</h6>
+    </div>
 {% endblock %}
 
 {% block content %}
@@ -15,13 +17,37 @@
     {% filter to_html %}
 # Welcome to PyDRex!
 
-> This is the documentation website for [PyDRex](https://github.com/seismic-anisotropy/PyDRex),
+> This is the documentation website for [PyDRex](https://pypi.org/project/pydrex/),
 a Python implementation of the D-Rex model for kinematic texture simulations.
-Use the links below to browse the API documentation or the tests and examples:
+Click the buttons below to browse the documentation or read about the tests and examples.
+    {% endfilter %}
+
+    <br>
+
+    <blockquote>
+    <a href="pydrex.html"><button class="button">Documentation</button></a>
+    <a href="tests.html"><button class="button">Tests & Examples</button></a>
+    </blockquote>
+
+    <br>
+
+    {% filter to_html %}
+> The `pydrex` package is published on PyPI (the Python Package Index).
+The source code is hosted on GitHub, with an issue tracker and discussion page.
     {% endfilter %}
 
-    <blockquote><a href="pydrex.html"><button class="button">API Documentation</button></a>
-    <a href="tests.html"><button class="button">Tests & Examples</button></a></blockquote>
+    <br>
+
+    <blockquote>
+    <a href="https://pypi.org/project/pydrex/"><button class="button">
+    Package&nbsp;
+    <img height="33px" src="https://pypi.org/static/images/logo-small.8998e9d1.svg" alt="PyPI logo"/>
+    </button></a>
+    <a href="https://github.com/seismic-anisotropy/PyDRex"><button class="button">
+    Source code&nbsp;
+    <img height="33px" src="https://github.githubassets.com/favicons/favicon.svg" alt="GitHub logo"/>
+    </button></a>
+    </blockquote>
 
     </main>
     {% include "search.html.jinja2" %}

docs/template/theme.css

@@ -38,8 +38,17 @@
   }
 }
 
-.homediv { padding-top: 56px; max-width: 1080px; }
+/* Center search box and version number in nav bars. */
+/* Then fix up internal div display with some margins. */
+input { display: block; margin: auto; }
+nav h6 { text-align: center; }
+nav div { padding-right: 8%; }
+
+/* Add padding for nav bar footer in case of long version numbers (dev docs). */
+nav footer { padding-right: 5px; }
 
+/* Styles for greeting page and buttons. */
+.homediv { padding-top: 56px; max-width: 1080px; }
 .button {
     background-color: var(--muted);
     color: var(--pdoc-background);
@@ -55,10 +64,11 @@
     cursor: pointer;
     width: 48%;
 }
-
 .button:hover {
     background-color: var(--text);
     color: var(--active);
 }
 
+/* Render display equations in horizontally scrollable box. */
+/* Also tries to hide the scroll bar (sometimes it doesn't work). */
 .katex-display { overflow: auto hidden }