Summary
Building the Python binding docs with uv run mkdocs build / serve warns that MkDocs 1.x is unmaintained, and MkDocs 2.x has its own issues. Migrate the setup to Zensical, the successor to MkDocs + Material for MkDocs (built by the same team). Zensical builds from the existing mkdocs.yml, and preserves URLs and anchors.
Compatibility (verified)
The current setup lives in bindings/python/mkdocs.yml + pyproject.toml. All Markdown extensions in use are supported by Zensical: pymdownx.highlight, pymdownx.tabbed, pymdownx.details, pymdownx.snippets, pymdownx.superfences (+ Mermaid), pymdownx.emoji (twemoji), admonition, tables, toc, attr_list, plus content.code.copy and search.
mkdocstrings (used for the whole API reference) has preliminary support in Zensical since 0.0.11, configured via the same mkdocs.yml block.
Scope (bindings/python/)
pyproject.toml docs group: replace mkdocs + mkdocs-material with zensical, and install mkdocstrings-python separately (Zensical does not bundle it).
- Build/serve via the Zensical CLI; keep
mkdocs.yml.
- Update the
build-python-doc job in .github/workflows/docs.yml (output stays site/).
- Update the
docs recipes in bindings/python/justfile.
Incompatibility: mkdocs-jupyter
Zensical does not support mkdocs-jupyter, which currently renders the example notebooks (docs/examples/{basic,pandas,polars}.ipynb, referenced in nav). Replace it with nbconvert: pre-convert the notebooks to Markdown in the build step, reference the generated .md files in nav, and drop the mkdocs-jupyter dependency.
Out of scope
Fixing the broken Python API reference links is tracked separately in #7870. Zensical preserves URLs and anchors, so it does not change that behavior.
Summary
Building the Python binding docs with
uv run mkdocs build/servewarns that MkDocs 1.x is unmaintained, and MkDocs 2.x has its own issues. Migrate the setup to Zensical, the successor to MkDocs + Material for MkDocs (built by the same team). Zensical builds from the existingmkdocs.yml, and preserves URLs and anchors.Compatibility (verified)
The current setup lives in
bindings/python/mkdocs.yml+pyproject.toml. All Markdown extensions in use are supported by Zensical:pymdownx.highlight,pymdownx.tabbed,pymdownx.details,pymdownx.snippets,pymdownx.superfences(+ Mermaid),pymdownx.emoji(twemoji),admonition,tables,toc,attr_list, pluscontent.code.copyandsearch.mkdocstrings(used for the whole API reference) has preliminary support in Zensical since 0.0.11, configured via the samemkdocs.ymlblock.Scope (
bindings/python/)pyproject.tomldocs group: replacemkdocs+mkdocs-materialwithzensical, and installmkdocstrings-pythonseparately (Zensical does not bundle it).mkdocs.yml.build-python-docjob in.github/workflows/docs.yml(output stayssite/).docsrecipes inbindings/python/justfile.Incompatibility:
mkdocs-jupyterZensical does not support
mkdocs-jupyter, which currently renders the example notebooks (docs/examples/{basic,pandas,polars}.ipynb, referenced innav). Replace it with nbconvert: pre-convert the notebooks to Markdown in the build step, reference the generated.mdfiles innav, and drop themkdocs-jupyterdependency.Out of scope
Fixing the broken Python API reference links is tracked separately in #7870. Zensical preserves URLs and anchors, so it does not change that behavior.