Skip to content

Prune patchwork Sphinx config; add class inheritance diagrams#119

Open
levon003 wants to merge 1 commit into
docs/fix-rst-warningsfrom
docs/sphinx-config-cleanup
Open

Prune patchwork Sphinx config; add class inheritance diagrams#119
levon003 wants to merge 1 commit into
docs/fix-rst-warningsfrom
docs/sphinx-config-cleanup

Conversation

@levon003

Copy link
Copy Markdown
Member

Addresses items 1, 2, 5, and 7 of #117 — the cleanup of the matplotlib/pydata template cruft in docs/conf.py.

Stacked on #118 (base is docs/fix-rst-warnings). GitHub will auto-retarget to main when #118 merges. Review/merge after #118.

Removed (all verified unused — make html SPHINXOPTS="-W --keep-going" is clean without them)

  • sphinx.ext.linkcode + the 55-line linkcode_resolve() — verbatim matplotlib boilerplate that always returned None here (it guards on matplotlib/ paths). viewcode already provides the working [source] links. (item 1)
  • The no-op docutils_conf dict — Sphinx never reads a module-level variable by that name. (item 2)
  • numpydoc — the codebase is 100% Google-style (handled by napoleon), and its class-member tables were already disabled, so it did nothing. Dropping it also removes the numpydoc_show_class_members workaround. (item 5)
  • The three matplotlib.sphinxext.* extensions and sphinx_design / sphinx_tags — no directive uses them. Their packages are removed from the docs dependency group too. (item 5)
  • Now-unused conf.py imports (inspect, Path, parse_version, flexeval).

Net: conf.py loses ~87 lines.

Added

  • Two inheritance_diagram diagrams on the API page (item 5 — "use it rather than remove it"): the polymorphic DataSource hierarchy and the peewee model hierarchy. These need Graphviz, so both CI workflows now apt-get install graphviz, and DEVELOPMENT.md documents the local prerequisite (brew install graphviz).
  • DEVELOPMENT.md: notes that CI builds with -W (warnings = errors) and how to reproduce locally, plus a make linkcheck pointer (item 7 — documented, not automated, since it makes network requests).

Notes / left for you

  • sphinxext.github (the local extension defining :ghissue:/:ghpull: roles) is also currently unused, but I kept it — it's a self-contained local utility (handy for release notes), not imported template cruft. Easy to drop if you'd rather.
  • This is a docs/config-only change (nothing ships in the wheel), so no version bump — the 0.5.3 bump on Fix malformed-RST docstring warnings and enable -W in CI #118 covers the release.

🤖 Generated with Claude Code

The conf.py was largely lifted from the matplotlib/pydata doc templates and
carried a lot of unused machinery. Remove what isn't used and wire up the one
piece worth keeping.

Removed (all verified unused; build is clean under -W without them):
- sphinx.ext.linkcode + the 55-line linkcode_resolve(), which was verbatim
  matplotlib boilerplate that always returned None here. viewcode already
  provides the working "[source]" links.
- The no-op docutils_conf dict (Sphinx never reads a module-level var by that
  name).
- numpydoc: the codebase is 100% Google-style (napoleon handles that), and its
  class-member tables were already disabled, so it did nothing. Dropping it also
  lets the numpydoc_show_class_members workaround go.
- The three matplotlib.sphinxext.* extensions and sphinx_design / sphinx_tags,
  none of which are used by any directive. Their packages are dropped from the
  docs dependency group too.
- Now-unused conf.py imports (inspect, Path, parse_version, flexeval).

Added:
- Two sphinx.ext.inheritance_diagram diagrams on the API page (the DataSource
  hierarchy and the peewee model hierarchy). These need Graphviz, so both CI
  workflows now install it and DEVELOPMENT.md notes the local prerequisite.
- DEVELOPMENT.md notes that CI builds with -W (warnings are errors) and how to
  reproduce locally, plus a `make linkcheck` pointer.

Addresses items 1, 2, 5, and 7 of #117.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant