docs: Document refactored tracing #936
Conversation
- Disordered tracing - Nodestats - Ordered tracing - Splining
As per Markdown linting defined in `.markdownlint-cli2.yaml` - Wrap lines at 120 characters. - Fix all other linting errors automatically.
As per [myst docs](https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#auto-generated-header-anchors) setting the `myst_heading_anchors` sets the maximum depth for auto-generating label "slugs" for section headers. Helps resolve some, but not all, complaints about internal links.
Myst-Parser complains about the use of Markdown footnotes (e.g. `[^1]`) therefore switch these to alternatives.
…sheffield/btr-docs
|
@ns-rse you've requested a review, but this is still a draft, so are you happy with the toctrees?
And shall I re-examine the docs to ensure everything is rendered ok? (Also, how do I do this for CI and not local e.g. to see if the equations are loaded correctly?) |
|
Evening @MaxGamill-Sheffield Not completely happy with Its slightly obfuscated but the commands to replicate what CI does using sphinx-multiversion . _build/html "../*setup*" "../*tests*" "../*.ipynb" ../demo.py ../make_baseline.py ../jupyter_notebook_config.py ../demo_ftrs.pyWeirdly using I add reviewers to drafts when creating them (so I don't forget when I hit the "Ready for review") but in this instance will see if making it "Ready for review" triggers the build. If not and for expedience I will rejig how the advanced docs are linked from the front page. |
…sheffield/btr-docs
|
Not sure I'm understanding this. Is the issue that we aren't able to check that they're rendering okay on gh-pages? If so, if we are happy with the contents could we try just pushing to main which would presumably force a build? |
Correct.
This would result in the I'm going to look at this today and may just ditch having an additional |
The second `.. toctree::` was not being rendered for some reason. Instead a new page `docs/advanced.md` has been created and serves as an index to the documentation which resides under `advanced/` with sub-headings for each section as I can envisage this growing as more functionality is added.
|
Ready for review, its not triggering the GitHub Action to build the documentation here on GitHub because that is configured to only run on Pull Requests that target the I couldn't work out how to get the second |
MaxGamill-Sheffield
merged commit f476c65
into
maxgamill-sheffield/800-better-tracing
Adds documentation, written by @MaxGamill-Sheffield, for...
I squashed the history of all the incremental commits that wrote this documentation but have left the changes I've made recently as individual commits.
Locally the
advancedTable of Contentes (toctree) is not rendered, I need to check if this is the case on the GitHub CI rendered pages too though (which this PR should trigger).NB Ideally this should be merged to
maxgamill-sheffield/800-better-tracingbefore it is merged tomainso the documentation and features arrive onmainat the same time.