Use jupytext and replace notebooks by Markdown

[volkm]

The documentation now uses Myst Markdown together with Jupytext to support Jupyter notebooks. This allows better git integration.
The existing notebooks have been removed, but the command make notebooks automatically builds all notebooks next to their corresponding Markdown files.
Use make check-doc to ensure that all generated notebooks can be executed successfully. This is also checked in the CI.
Use make format to execute formatting: for cpp files via the script in resources, for Python via black and for the Markdown documentation via black as well.

[Copilot]

🟡 Changes recommended

The new doc tooling wiring has a few concrete issues (notably make check-doc using --test-strict with no tracked .ipynb, missing jupytext in the doc extra for the documented workflow, and a path normalization bug for binder badge detection).

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR migrates the Sphinx documentation from tracked .ipynb notebooks to MyST Markdown sources paired via Jupytext, improving diffability and enabling reproducible notebook generation/execution checks in CI.

Changes:

• Replace committed documentation notebooks with .md (MyST) sources containing executable {code-cell} blocks and Jupytext front matter.
• Add repo-level Makefile targets for formatting, notebook generation, and documentation execution checks.
• Update Sphinx configuration/theme templates and CI workflows to support myst-nb, binder badges, and doc-format/doc-execution checks.

File summaries

File	Description
pyproject.toml	Updates optional dependency groups for docs/dev/testing.
Makefile	Adds formatting, notebook generation, and doc execution targets.
doc/source/using_pycarl.md	Converts examples to MyST/Jupytext-compatible notebook Markdown.
doc/source/installation.md	Updates MyST directive syntax and doc build instructions.
doc/source/index.md	Converts to MyST fenced toctree.
doc/source/getting_started.md	Adds MyST/Jupytext versioned notebook Markdown replacement.
doc/source/getting_started.ipynb	Removes tracked notebook in favor of Markdown source.
doc/source/doc/simulator.md	Adds MyST/Jupytext notebook Markdown replacement.
doc/source/doc/simulator.ipynb	Removes tracked notebook in favor of Markdown source.
doc/source/doc/shortest_paths.md	Adds MyST/Jupytext notebook Markdown replacement.
doc/source/doc/shortest_paths.ipynb	Removes tracked notebook in favor of Markdown source.
doc/source/doc/schedulers.md	Adds MyST/Jupytext notebook Markdown replacement.
doc/source/doc/schedulers.ipynb	Removes tracked notebook in favor of Markdown source.
doc/source/doc/reward_models.md	Adds MyST/Jupytext notebook Markdown replacement.
doc/source/doc/reward_models.ipynb	Removes tracked notebook in favor of Markdown source.
doc/source/doc/parametric_models.md	Adds MyST/Jupytext notebook Markdown replacement.
doc/source/doc/parametric_models.ipynb	Removes tracked notebook in favor of Markdown source.
doc/source/doc/models/building_mdps.md	Adds MyST/Jupytext notebook Markdown replacement for MDP building docs.
doc/source/doc/models/building_mdps.ipynb	Removes tracked notebook in favor of Markdown source.
doc/source/doc/models/building_mas.md	Adds MyST/Jupytext notebook Markdown replacement for MA building docs.
doc/source/doc/models/building_mas.ipynb	Removes tracked notebook in favor of Markdown source.
doc/source/doc/models/building_dtmcs.md	Adds MyST/Jupytext notebook Markdown replacement for DTMC building docs.
doc/source/doc/models/building_dtmcs.ipynb	Removes tracked notebook in favor of Markdown source.
doc/source/doc/models/building_ctmcs.md	Adds MyST/Jupytext notebook Markdown replacement for CTMC building docs.
doc/source/doc/models/building_ctmcs.ipynb	Removes tracked notebook in favor of Markdown source.
doc/source/doc/info.md	Adds MyST/Jupytext notebook Markdown replacement.
doc/source/doc/info.ipynb	Removes tracked notebook in favor of Markdown source.
doc/source/doc/gspns.md	Adds MyST/Jupytext notebook Markdown replacement.
doc/source/doc/gspns.ipynb	Removes tracked notebook in favor of Markdown source.
doc/source/doc/exploration.md	Adds MyST/Jupytext notebook Markdown replacement.
doc/source/doc/exploration.ipynb	Removes tracked notebook in favor of Markdown source.
doc/source/doc/engines.md	Adds MyST/Jupytext notebook Markdown replacement.
doc/source/doc/engines.ipynb	Removes tracked notebook in favor of Markdown source.
doc/source/doc/dfts.md	Adds MyST/Jupytext notebook Markdown replacement.
doc/source/doc/dfts.ipynb	Removes tracked notebook in favor of Markdown source.
doc/source/doc/building_models.md	Adds MyST/Jupytext notebook Markdown replacement.
doc/source/doc/building_models.ipynb	Removes tracked notebook in favor of Markdown source.
doc/source/doc/analysis.md	Adds MyST/Jupytext notebook Markdown replacement.
doc/source/doc/analysis.ipynb	Removes tracked notebook in favor of Markdown source.
doc/source/conf.py	Switches Sphinx notebook support to myst-nb, adds execution caching, and passes notebook page list to templates.
doc/source/api.md	Converts to MyST fenced toctree.
doc/source/advanced_topics.md	Converts to MyST fenced toctree.
doc/source/_templates/page.html	Adds binder badge injection for notebook-backed pages.
doc/source/_static/custom.css	Updates styling for binder badge and myst-nb cell output formatting.
doc/build_website.md	Updates documentation build instructions and describes notebook workflow.
binder/requirements.txt	Adds jupytext and pins spellchecker version for binder.
binder/Dockerfile	Switches binder notebook sources to .md and regenerates .ipynb via jupytext at build time.
.gitignore	Ignores generated .ipynb and myst-nb execution cache directory.
.github/workflows/formatcheck.yml	Adds a doc-format check job using make check-format-doc.
.github/workflows/create_wheel.yml	Removes nbval from wheel-test dependency install.
.github/workflows/buildtest.yml	Runs make check-doc in CI and removes pandoc installation step.

Review details

Suppressed comments (2)

doc/source/conf.py:130

• notebook_docs is built from str(Path(...)), which will use OS-specific separators (e.g. doc\\simulator on Windows). Sphinx’s pagename uses POSIX-style paths, so the binder badge check (pagename in notebook_docs) can fail on non-POSIX builds. Normalize to POSIX paths when populating notebook_docs.

# Documentation pages that are paired jupytext notebooks (used for binder badges)
_source_dir = pathlib.Path(__file__).parent
notebook_docs = sorted(str(p.relative_to(_source_dir).with_suffix("")) for p in _source_dir.rglob("*.md") if "jupytext:" in p.read_text(errors="ignore")[:500])
html_context = {"notebook_docs": notebook_docs}

doc/build_website.md:17

• This section refers to check-doc, but that’s a Makefile target; the documented command should be make check-doc (otherwise it reads like a standalone executable).

## Jupyter notebooks
The documentation uses [Myst Markdown](https://mystmd.org/) together with [Jupytext](https://jupytext.org/) to support Jupyter notebooks.
The command `make notebooks` automatically builds all notebooks next to their corresponding Markdown files.
Use `check-doc` to ensure that all generated notebooks can be executed successfully. This is also checked in the CI.

• Files reviewed: 50/51 changed files
• Comments generated: 6
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.