Skip to content

docs(python): migrate MkDocs setup to Zensical #7871

Description

@chitralverma

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    bindings/pythondocumentationImprovements or additions to documentationreleases-note/docsThe PR modifies docs related content or has a title that begins with "docs"

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions