warm start for the docs build

[kip-hart]

Read the Docs stops a build at fifteen minutes on the free plan. The
documentation build runs every example in src/microstructpy/examples to
produce the figures the pages embed, which takes about twenty minutes on that
class of hardware, so the build cannot finish. Every build that gets as far as
running the examples is stopped at 901 seconds, including 3697c378, the head
of #114 as I write this.

The examples produce the same figures every time. This moves that work to the
documentation workflow, which has no time limit, and has Read the Docs restore
what it produced.

How it works

Sphinx-Gallery already skips a script whose hash matches the .md5 stored
beside the output of an earlier build. The difficulty is that
docs/source/sphinx_gallery/plot_demos.py finds the examples with glob and
names none of them, so its hash does not move when an example is edited or
added, nor when the library that meshes them changes. Caching on that hash
alone would serve stale figures and never report it.

docs/example_digest.py closes that gap. It digests the example inputs and the
library source and keeps the result in plot_demos.py as EXAMPLES_DIGEST.
Editing an example changes the digest, which changes the hash of the script,
which makes Sphinx-Gallery run the examples again. The documentation check runs
it with --check and fails if the stored digest is out of date.

docs/example_cache.py packs and restores the Sphinx-Gallery output and the
PNG files the examples write, which the pages embed with figure::. An archive
carries the digest it was built from, and restore refuses one that does not
match the working tree. A build that cannot be warm runs the examples and may
time out rather than publish stale figures.

The html job publishes an archive to the docs-cache release, named by the
digest, and asks Read the Docs to build again so the archive is picked up. A
post_install job on Read the Docs fetches the archive for the digest of the
commit it is building, and restores it if the digests match.

Measurements

Locally, with the examples run on the same machine:

cold build                  655.4 s
warm build                    6.7 s
warm build with -W            6.0 s

On Read the Docs, across the commits of this branch:

before                        901 s   timed out
no archive published yet      901 s   timed out
archive available              66 s   passed

The timeouts are the intended behavior when no archive matches the commit. The
first build after a change to an example or to the library runs the examples,
fails, and goes green once the html job has published an archive and asked
for a rebuild.

Two other fixes

mesh_max_edge_length in basalt_circle.xml goes from 0.01 to 0.02. That
example was the largest single consumer of the build at 216 s, 29% of the 741 s
the examples take in total. About 180 s of it was meshing, driven by this
setting on a domain of diameter 10:

0.01 (before)  216.2 s
0.02            114.4 s
0.03             83.7 s
0.05             63.8 s

0.02 halves it, and coarser values give much less back. The rendered figure is
unchanged at publication size, with slightly coarser triangles inside the large
olivine grains.

elliptical_grains.xml declared <?xml version="0.5" ... ?>. The XML
specification allows only 1. followed by digits, production [26], so the
declaration has never been well formed. Expat 2.6.1 accepts it and newer
versions reject it, which is why this passed locally and failed on some runners,
and why the documentation check looked flaky: it failed in one format and passed
in another on the same commit. The file is older than this branch, and it was
the only one in the repository with an illegal version.

fail-fast: false on the documentation matrix, so one failing format no longer
cancels the other two. python_package.yaml already sets it.

Setting it up

The rebuild needs a READTHEDOCS_TOKEN secret, from Settings and then API
Tokens on Read the Docs. Without it the step says so and does nothing, and a
build that has to wait for an archive must be restarted by hand.

Nothing is committed to the repository. The archives are release assets, 13.9 MB
each, so docs/source/auto_examples and the output directories of the examples
stay ignored.

Notes

The archive is only restored when its digest is the digest of the commit being
built, so an edited example is never served with the figures of an older one.
Three archives are published so far, one per digest.

docs/README.rst covers building the documentation, how the cache works, and
how to publish one by hand.