Conversation
The documentation build runs every example in src/microstructpy/examples
(docs/source/sphinx_gallery/plot_demos.py globs and runs them all), and
nothing is cached between Read the Docs builds. The periodic examples
added on this branch pushed that past the 15 minute limit of the Read
the Docs free plan.
basalt_circle is the single largest consumer at 216 s, 29% of the 741 s
the examples take in total, and more than any of the new examples. About
180 s of that is meshing, driven by mesh_max_edge_length on a domain of
diameter 10.
Measured on the same machine:
0.01 (before) 216.2 s
0.02 114.4 s
0.03 83.7 s
0.05 63.8 s
0.02 halves the example. Coarser values give much less back, since what
remains is positioning 1300 seeds, plotting them and verification. The
rendered figure is unchanged at publication size, with slightly coarser
triangles inside the large olivine grains.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
A build on Read the Docs is stopped at fifteen minutes on the free plan.
The documentation build runs every example in src/microstructpy/examples
through docs/source/sphinx_gallery/plot_demos.py, which takes about
twenty minutes on that class of hardware, so the build cannot finish. The
examples produce the same figures every time, so this moves the work to
the documentation workflow, which has no such limit, and has Read the
Docs restore what it produced.
Sphinx-Gallery already skips a script whose hash matches the .md5 beside
the output of an earlier build. The difficulty is that 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, so editing any of them changes the hash of the script
and the examples run 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, so a build that cannot be warm runs
the examples and may time out rather than publish stale figures.
Measured locally, with the examples run on the same machine:
cold build 655.4 s
warm build 6.7 s
The documentation workflow publishes an archive from its html job to the
docs-cache release, and asks Read the Docs to build again so the archive
is picked up. That rebuild needs a READTHEDOCS_TOKEN secret. Without it
the step says so and does nothing, and the build has to be restarted by
hand once the archive is published.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
TBD