chitralverma opened a new issue, #7871: URL: https://github.com/apache/opendal/issues/7871
# 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](https://zensical.org/), 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](https://zensical.org/docs/setup/extensions/mkdocstrings/) 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](https://nbconvert.readthedocs.io/): 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. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
