Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: use sphinxdocs for docgen #115

Draft
wants to merge 1 commit into
base: master
Choose a base branch
from

Conversation

rickeylev
Copy link
Contributor

This switches the doc generation over to use rules_python's sphinxdocs. Sphinxdocs
is a set of rules for running Sphinx with special integrations for Starlark
doc generation.

The main benefits of this switch are:

  • Sphinx is entirely run through Bazel (instead of a bespoke shell script
    to glue together outputs of Bazel invocations)
  • Sphinxdocs comes with a Sphinx plugin that allows defining Starlark objects
    as first-class objects to Sphinx. These are usually generated by the Stardoc
    integration, but can also be manually defined to document e.g. targets or flags.
  • Sphinxdocs supports defining "typedefs", which is a way to group a collection of
    objects and have them rendered similar to how a class is rendered in other languages.
    Part of what this change does is update all the subject "classes" to render as
    "typedefs".
  • Cross references are easier and more automatic. Because Sphinx understands the
    objects being defined, cross references have a more natural, concise, and expressive
    notation.
  • Sphinxdocs has helpers for interactively running docs for easier edit/run cycles
  • Sphinxdocs has helpers for using Bazel to build the docs as part of readthedocs
    workflows (this ensures what is built locally matches what is built by RTD).

@rickeylev rickeylev force-pushed the sphinxdocs branch 5 times, most recently from abf37f1 to 06181ca Compare October 19, 2024 22:51
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