timsaucer opened a new pull request, #1586: URL: https://github.com/apache/datafusion-python/pull/1586
# Which issue does this PR close? N/A # Rationale for this change The documentation site previously used Sphinx + MyST with a mix of reStructuredText and Markdown sources. This PR migrates the full site to MkDocs with the Material theme and `mkdocstrings` for API reference generation. Motivations: - Markdown is the format new contributors already know. RST directives (`.. autoclass::`, `:ref:`) are a friction point. - LLM-based contributors and reviewers parse Markdown reliably; RST is hit-or-miss. - Material for MkDocs ships a stronger default UX out of the box (search, navigation, dark mode, code copy) without piecing together Sphinx extensions. - `mkdocs serve` provides a faster, more reliable live-reload loop than `sphinx-autobuild` for this project's content set. # What changes are included in this PR? - Documentation sources converted from reStructuredText (and MyST) to plain Markdown, with the navigation tree expressed in `mkdocs.yml`. - API reference generation moved from Sphinx `autodoc` to `mkdocstrings` with Google-style docstrings. - User guide pages updated to use `markdown-exec` for executable code blocks (replacing the previous Jupyter-based pipeline), with shared setup centralized in a small hook. - Links, anchors, and admonitions swept for consistency; broken cross-references and duplicate TOC entries fixed. - Public API surface tightened so the generated reference matches what users are expected to import. - Cross-references inside Python docstrings use sphinx-style roles (`:func:`, `:class:`, `:meth:`, `:attr:`) so that IDE hovers render clickable links. A small `griffe` extension rewrites these roles into `mkdocstrings` autorefs at build time, so the published site continues to link correctly. - A test asserts that all public modules surface on the documentation site, guarding against future drift. # Are there any user-facing changes? The published documentation site has a new look and navigation structure but the same hosting URL. There are no API or behavior changes to the `datafusion` Python package itself. Contributors writing new pages or docstrings should follow the MkDocs/Markdown conventions described in `CLAUDE.md` and the user guide. -- 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] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
