[py] Improve generated HTML docs for Python API

[cgoldberg]

💥 What does this PR do?

This PR improves the generated HTML docs for the Python API. The existing ones are really difficult to navigate and read.

Changes:

• Replaced sphinx-material theme with: pydata-sphinx-theme

  • This is a more modern theme with a responsive design and better configuration options. It is also actively maintained and (IMO) looks much nicer than the previous theme
  • Includes switchable light/dark mode (defaults to system setting)

• Cleaned up sphinx configuration (conf.py)

  • Removed config sections for output types we no longer support (man pages, epub, etc)

• Removed unused sphinx extensions:

  • sphinx.ext.doctest
  • sphinx.ext.todo
  • sphinx.ext.coverage
  • sphinx.ext.imgmath

• Added sphinx.ext.napoleon extension

  • This allows sphinx to parse Google style docstrings so parameters are rendered correctly

• Included type annotations for attributes and method/function signatures

• Made inheritance and class hierarchy more excplit

• Pinned new dependencies and lock file

---

Example of old docs:

Example of new docs (light mode):

Example of new docs (dark mode):

---

🤖 AI assistance

• No substantial AI assistance used
• AI assisted (complete below)
  • Tool(s):
  • What was generated:
  • I reviewed all AI output and can explain the change

🔄 Types of changes

• Documentation
• Enhancement

[qodo-code-review]

PR Summary by Qodo

Improve Python API HTML docs: switch to pydata-sphinx-theme + better autodoc output

📝 Documentation ✨ Enhancement ⚙️ Configuration changes 🕐 10-20 Minutes

AI Description

• Switch Sphinx HTML theme to pydata-sphinx-theme with built-in light/dark switching.
• Improve API reference readability via napoleon + rendering type hints in descriptions.
• Clean up Sphinx outputs/extensions and update Bazel + pinned/locked docs dependencies.

Diagram

graph TD
  A["Bazel //py:docs"] --> B["sphinx-build target"] --> C["Sphinx"] --> H["Generated HTML docs"]
  F["docs/source/conf.py"] --> C
  G["requirements*.txt"] --> B
  C --> D["pydata theme"] --> H

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Use Furo theme

• ➕ Modern UI with strong defaults and simple configuration
• ➕ Popular in Python projects; generally lightweight
• ➖ Different navigation/sidebars than pydata; may require extra customization to match desired layout
• ➖ Less built-in “docs portal” style compared to pydata theme

2. Use sphinx_rtd_theme (Read the Docs)

• ➕ Very common and familiar UI for many users
• ➕ Often minimal additional configuration required
• ➖ Less modern look-and-feel than pydata theme
• ➖ Theme switching and navbar customization may be less ergonomic

Recommendation: The chosen approach (pydata-sphinx-theme + napoleon + typehint rendering) is a good fit for large API references: it improves navigation, supports theme switching out of the box, and makes docstrings/types more legible without custom templates. Alternatives mainly trade familiarity or simplicity for fewer built-in UX features.

Files changed (4) +107 / -330

Documentation (1) +42 / -123

conf.pyModernize Sphinx config: theme, napoleon, and richer autodoc output +42/-123

Modernize Sphinx config: theme, napoleon, and richer autodoc output

• Replaces the HTML theme with pydata_sphinx_theme and configures theme options (syntax highlighting styles, navbar links, theme switcher, simplified sidebar). Adds sphinx.ext.napoleon and enables autodoc type hints + defaults to include members/inheritance details, while removing legacy output configuration (LaTeX/man/epub blocks).

py/docs/source/conf.py

Other (3) +65 / -207

BUILD.bazelSwitch Sphinx build target to pydata-sphinx-theme +1/-1

Switch Sphinx build target to pydata-sphinx-theme

• Updates the Bazel sphinx-build console_script target to depend on pydata_sphinx_theme instead of sphinx-material, ensuring the doc build uses the new theme dependency.

py/BUILD.bazel

requirements.txtPin pydata-sphinx-theme and remove sphinx-material +1/-1

Pin pydata-sphinx-theme and remove sphinx-material

• Adds pydata-sphinx-theme to the dev requirements and removes sphinx-material so local/CI doc builds install the intended theme.

py/requirements.txt

requirements_lock.txtRegenerate lockfile for new Sphinx theme and transitive deps +63/-205

Regenerate lockfile for new Sphinx theme and transitive deps

• Updates the compiled lockfile to include pydata-sphinx-theme and its transitive dependencies (e.g., accessible-pygments) and to drop sphinx-material-only dependencies. Also reflects lock regeneration side effects such as a mypy version bump within the resolved set.

py/requirements_lock.txt

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📜 Skill insights (0)

Context used

✅ Compliance rules (platform): 17 rules

1. Docs theme reference stale ✓ Resolved 🐞 Bug ⚙ Maintainability

Description

py/docs/README.rst still claims the docs use sphinx-material, but conf.py now configures
pydata_sphinx_theme. This inconsistency can mislead contributors who follow the README to understand
or modify the docs toolchain.

Code

py/docs/source/conf.py[R116-117]

# The theme to use for HTML and HTML Help pages
-html_theme = "sphinx_material"
+html_theme = "pydata_sphinx_theme"

Evidence

The Sphinx configuration in this PR sets the HTML theme to pydata_sphinx_theme, while the docs
README still explicitly describes the theme as sphinx-material.

py/docs/source/conf.py[114-143]
py/docs/README.rst[41-46]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
`py/docs/README.rst` still states that the docs use the `sphinx-material` theme, but the Sphinx config now uses `pydata_sphinx_theme`.

### Issue Context
This PR changes the configured HTML theme in `py/docs/source/conf.py`, so any contributor-facing docs that describe the theme should be updated to match.

### Fix Focus Areas
- py/docs/README.rst[41-46]
- py/docs/source/conf.py[114-143]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Sidebar templates disabled ✗ Dismissed 🐞 Bug ≡ Correctness

Description

py/docs/source/conf.py sets html_sidebars to an empty list for all documents, which disables
rendering any Sphinx sidebar templates. With pydata_sphinx_theme, this can suppress the theme’s
standard sidebar navigation components (and makes sidebar-related options like show_toc_level
potentially ineffective).

Code

py/docs/source/conf.py[R178-180]

+html_sidebars = {
+    "**": [],
+}

Evidence

The config explicitly overrides all sidebar templates to an empty list, while also configuring
sidebar-related theme behavior (show_toc_level), indicating the docs likely expect a sidebar to
exist.

py/docs/source/conf.py[177-180]
py/docs/source/conf.py[122-127]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`html_sidebars = {"**": []}` disables Sphinx sidebar template rendering for every page. With `pydata_sphinx_theme`, this can unintentionally remove the primary navigation/sidebar components and render sidebar-related theme options ineffective.

## Issue Context
You recently switched `html_theme` to `pydata_sphinx_theme` and set `show_toc_level`, but the global empty `html_sidebars` override can prevent the theme’s sidebar templates from being included.

## Fix Focus Areas
- py/docs/source/conf.py[122-143]
- py/docs/source/conf.py[177-180]

## Suggested fix
- Remove the `html_sidebars` override entirely to allow the theme defaults to apply, **or**
- Replace it with an explicit list of sidebar templates you intend to keep (per the theme’s expected sidebar template names).

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. RST path markup wrong ✓ Resolved 🐞 Bug ⚙ Maintainability ⭐ New

Description

py/docs/README.rst marks the output directory with single backticks, which is interpreted-text
markup rather than an inline literal, so the rendered docs will format the filesystem path
inconsistently with other path literals in the same document.

Code

py/docs/README.rst[18]

+After building, docs are available in `bazel-bin/py/docs/_build/html/`

Evidence

The newly added output directory uses single backticks, while the same README uses double backticks
for inline-literal path formatting earlier in the file.

py/docs/README.rst[15-18]
py/docs/README.rst[5-6]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
The output directory path is wrapped in single backticks, which is interpreted-text markup in reStructuredText and renders differently than inline code/literal formatting.

### Issue Context
This README already uses inline-literal formatting (double backticks) for paths (e.g., ``py/docs``), so the output path should use the same literal markup for consistent rendering.

### Fix Focus Areas
- py/docs/README.rst[18-18]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Previous review results

Review updated until commit dea169a

Results up to commit 23a2612

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0) 🎨 UX issues (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

1. Sidebar templates disabled ✗ Dismissed 🐞 Bug ≡ Correctness

Description

py/docs/source/conf.py sets html_sidebars to an empty list for all documents, which disables
rendering any Sphinx sidebar templates. With pydata_sphinx_theme, this can suppress the theme’s
standard sidebar navigation components (and makes sidebar-related options like show_toc_level
potentially ineffective).

Code

py/docs/source/conf.py[R178-180]

+html_sidebars = {
+    "**": [],
+}

Evidence

The config explicitly overrides all sidebar templates to an empty list, while also configuring
sidebar-related theme behavior (show_toc_level), indicating the docs likely expect a sidebar to
exist.

py/docs/source/conf.py[177-180]
py/docs/source/conf.py[122-127]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`html_sidebars = {"**": []}` disables Sphinx sidebar template rendering for every page. With `pydata_sphinx_theme`, this can unintentionally remove the primary navigation/sidebar components and render sidebar-related theme options ineffective.

## Issue Context
You recently switched `html_theme` to `pydata_sphinx_theme` and set `show_toc_level`, but the global empty `html_sidebars` override can prevent the theme’s sidebar templates from being included.

## Fix Focus Areas
- py/docs/source/conf.py[122-143]
- py/docs/source/conf.py[177-180]

## Suggested fix
- Remove the `html_sidebars` override entirely to allow the theme defaults to apply, **or**
- Replace it with an explicit list of sidebar templates you intend to keep (per the theme’s expected sidebar template names).

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Results up to commit de7453a

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0) 🎨 UX issues (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

1. Docs theme reference stale ✓ Resolved 🐞 Bug ⚙ Maintainability

Description

py/docs/README.rst still claims the docs use sphinx-material, but conf.py now configures
pydata_sphinx_theme. This inconsistency can mislead contributors who follow the README to understand
or modify the docs toolchain.

Code

py/docs/source/conf.py[R116-117]

# The theme to use for HTML and HTML Help pages
-html_theme = "sphinx_material"
+html_theme = "pydata_sphinx_theme"

Evidence

The Sphinx configuration in this PR sets the HTML theme to pydata_sphinx_theme, while the docs
README still explicitly describes the theme as sphinx-material.

py/docs/source/conf.py[114-143]
py/docs/README.rst[41-46]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
`py/docs/README.rst` still states that the docs use the `sphinx-material` theme, but the Sphinx config now uses `pydata_sphinx_theme`.

### Issue Context
This PR changes the configured HTML theme in `py/docs/source/conf.py`, so any contributor-facing docs that describe the theme should be updated to match.

### Fix Focus Areas
- py/docs/README.rst[41-46]
- py/docs/source/conf.py[114-143]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

[qodo-code-review]

Code review by qodo was updated up to the latest commit ce7311c

[qodo-code-review]

Code review by qodo was updated up to the latest commit fdddbff

[diemol]

Nice!

[qodo-code-review]

Code review by qodo was updated up to the latest commit de7453a

[qodo-code-review]

Code review by qodo was updated up to the latest commit f844825

[qodo-code-review]

Code review by qodo was updated up to the latest commit dea169a