Fix the equation rendering, and document the coupling with tutorials - #16
Merged
Conversation
Closes #15. The documentation loaded KaTeX's script without its stylesheet. That stylesheet is what hides the MathML KaTeX emits alongside its own HTML output, so without it every equation was rendered twice: once by KaTeX and once by the browser as flattened MathML, which is the doubled, mangled symbols the issue reports. It typesets with MathJax now, the renderer the rest of the PROTEUS documentation uses, which needs no stylesheet of its own. The list of what an impact does was breaking after its fifth item, because the paragraph continuing that item was not indented and ended the list. Items six and seven were printed as running prose. `tools/check_docs_render.py` compares each built page against its source and fails on a list that lost items, on TeX that reached the page as text, and on a page whose maths renderer cannot style what it produces. It reads the built HTML rather than running the page, so it catches a renderer configured wrongly but not one that fails to load. The coupling pages gain what the framework side does with a schedule once it has one: the resolved timeline is written into the run's output directory, a resumed run replays that file when it is still there, and the same file can be replayed on its own or handed to someone without Morrigan installed. The offset is already applied when the file is written, which is worth knowing before replaying it. Two helpfile columns record the growth and the re-melt heat. The framework page shows the current PROTEUS lockup, with the fragments this theme switches on rather than the GitHub-only ones, and it now also shows the code architecture, where the accretion module and the loop stage that applies an impact are visible. Both figures are loaded from the PROTEUS repository rather than copied into this one. They are pinned to the branch that adds accretion to them, and return to following main once that work is merged; the checker reports the pin until they do. The links on the front page are laid out as cards, matching how the other module documentation presents them. The contact address is the current one, dev@proteus-framework.org.
Two tutorials. The first runs one system of six embryos standalone, from a settings file to a figure of the tracks, and reads off what the system did: four collisions inside the first 190 000 yr, one body grown from 0.60 to 3.30 Earth masses and one scattered outward without ever colliding. The figure is drawn in both colour schemes by `tools/plot_tutorial.py`, in the PROTEUS matplotlib theme, and carries the commit it came from. The second is one complete PROTEUS configuration that grows a planet by giant impacts with every other module set to dummy, so it runs in seconds; it loads through the configuration validator and the log it quotes is the log it produces. The other two modules in the same PROTEUS slot get a page each. `timeline` replays an impact history from a file, which is how a Morrigan-derived history is reproduced, shared, or handed to someone without Morrigan installed; the page carries the file format, what is checked when it loads, and the warning that the offset is already applied when PROTEUS writes it. `dummy` builds a history from scaling laws, deterministic and dependency-free, and the page explains what the growth law does and why `timeline_path` is refused there.
The figure now carries the version of the model that produced the run, with the commit that version points at, rather than the commit of whichever checkout happened to draw it. The PROTEUS tutorial says which PROTEUS and which Morrigan produced the log it quotes, since a different release can schedule a different history from the same seed. The plotting script names the run and the systems it found when asked for one that is not there, and takes a `--system` for a batch of more than one. The tutorials are reachable from the pages a reader arrives on: running a model points at the standalone one, the coupling recipe points at the PROTEUS one and at the two sibling modules, and the front page has a card for them. The initial orbits of the tutorial system read 0.30 to 0.52 AU, which is what the run lays out; the lower figure was wrong.
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
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.
What this does
Closes #15.
The equations were rendering twice, once typeset and once as a flattened, mis-ordered copy. The cause was not the dollar signs the issue suspected: the documentation loaded KaTeX's script without
katex.min.css. That stylesheet is what hides the MathML KaTeX emits next to its own HTML output, so without it the browser rendered both. The documentation now typesets with MathJax 3, the renderer PROTEUS, ZEPHYRUS, JANUS and MORS already use, which needs no stylesheet of its own.A second defect turned up on the same page: the seven-item list of what an impact does was breaking after item five, because the paragraph continuing that item was not indented, so items six and seven printed as running prose.
What else is in here
A checker.
tools/check_docs_render.pycompares each built page against its source and fails on a list that lost items, on TeX that reached the page as text, and on a page whose maths renderer cannot style what it produces. It is validated in both directions: against the build before this branch it reports exactly the defects above, and against the build after it reports none. It reads the built HTML rather than running the page, so it catches a renderer configured wrongly but not one that fails to load, and it says so.Two tutorials. One runs a system of six embryos standalone, from a settings file to a figure of the tracks; the other is a complete PROTEUS configuration that grows a planet by giant impacts with every other module set to dummy. Both were executed rather than written from memory: every number, every log line and the figure come from those runs, and the PROTEUS configuration loads through the configuration validator.
The other two accretion modules get a page each.
timelinereplays an impact history from a file, which is how a Morrigan-derived history is reproduced, shared, or handed to someone without Morrigan installed;dummybuilds one from scaling laws. Both are PROTEUS modules rather than Morrigan ones, documented here because they occupy the same slot and because a Morrigan run produces exactly the filetimelineconsumes.The coupling pages gain what the framework does with a schedule once it has one: it is written to the run's output directory, a resumed run replays that file, and the same file can be replayed on its own. The offset is already applied when the file is written, which is worth knowing before replaying it.
Presentation. The framework page shows the current PROTEUS lockup rather than the previous logo, and now also the code architecture, where the accretion module and the loop stage that applies an impact are visible. Both PROTEUS figures are loaded from the PROTEUS repository rather than copied into this one. The front page lays its links out as cards, matching the other module documentation, and the contact address is the current one.
Validation
zensical build --cleanis warning-free;tools/check_docs_render.pyreports no problems.One thing to know before merging
docs/proteus-framework.mdpins the four PROTEUS figure URLs to thetl/accretion-morrigan-couplingbranch, becausemainhas accretion in neither figure yet. They return to@mainonce PROTEUS#789 is merged, and the checker prints the outstanding pin on every build until then.