docs: integrate myst-nb notebook rendering infrastructure (#884)#885
Merged
Conversation
- Replace myst-parser with myst-nb (superset) for notebook execution - Add jupyter-cache and jupytext as docs dependencies - Configure nb_execution_mode='cache' with 120s timeout - Exclude .ipynb from Sphinx source (use .py via nb_custom_formats) - Create .py jupytext pair for backtesting tutorial - Tag SPDX cells with 'remove-cell' to hide from rendered output - Add symlink docs/source/tutorials -> examples/tutorials - Add poe notebooks-clear task (strip outputs from .ipynb) - Extend poe notebooks-check with output validation script - Add tools/check_notebook_outputs.py for CI validation - Wire 3 tutorials into Examples toctree - Exclude backtesting notebook from execution (too slow, tracked in #884) - Add E501/PTH lint ignores and pyright exclusion for tutorials - Document notebook workflow in Contributing guide - Add .jupyter_cache/ to .gitignore, tutorial .py to REUSE.toml Closes #884 (Phase 1) Signed-off-by: Egor Dmitriev <egor.dmitriev@alliander.com> Signed-off-by: Egor Dmitriev <egor.dmitriev@alliander.com>
egordm
force-pushed
the
docs/notebook-integration
branch
from
e26a002 to
d51431d
Compare
9 tasks
egordm
changed the title
This was referenced May 13, 2026
lschilders
reviewed
May 15, 2026
Remove the docs/source/tutorials symlink (breaks on Windows without Developer Mode) and replace with a poe _docs_sync task that copies examples/tutorials/ into docs/source/ before building. The docs task now has deps = ['_docs_sync'] so the copy runs automatically before sphinx-build or sphinx-autobuild. Signed-off-by: Egor Dmitriev <egor.dmitriev@alliander.com>
Signed-off-by: Egor Dmitriev <egor.dmitriev@alliander.com> Signed-off-by: Egor Dmitriev <egor.dmitriev@alliander.com>
egordm
force-pushed
the
docs/notebook-integration
branch
from
5821ff4 to
cd7734f
Compare
|
lschilders
approved these changes
May 15, 2026
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
2 participants
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.
Summary
Integrates myst-nb into the Sphinx docs build so tutorial notebooks in
examples/tutorials/render as notebook pages with code cells and narrative prose.This is Phase 1 of the documentation infrastructure plan from #884.
Changes
Docs build
myst-parserwithmyst-nb(superset that adds notebook execution)jupyter-cacheandjupytextas docs dependenciesnb_execution_mode="off"(execution enabled in follow-up [OpenSTEF 4.0] Optimize tutorial notebooks for CI execution #886).ipynbfrom Sphinx source tree (use.pyvianb_custom_formats)rstjinjahandler to skip non-RST sources (prevent Jinja errors on{}in notebooks)docs/source/tutorials→examples/tutorialsNotebooks
.pyjupytext pair for backtesting tutorialremove-cellto hide license boilerplate from rendered outputTooling
poe notebooks-cleartask (strip outputs from.ipynb)poe notebooks-checkwith output validation viatools/check_notebook_outputs.pyConfiguration
E501/PTHlint ignores for tutorials (educational code, not production)examples/tutorials/from pyright (notebooks have cell-scoped execution).jupyter_cache/to.gitignore.pyfiles toREUSE.tomlDocumentation
Verification
poe all✅ (1020 tests pass, lint clean, types clean, notebooks synced)poe docs✅ (build succeeds, tutorials render without SPDX leakage)Follow-up
nb_execution_mode="cache", switch to PNG plotting backendRelated