-
-
Notifications
You must be signed in to change notification settings - Fork 632
docs: initial doc generation using Sphinx #1489
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
Conversation
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Really interesting, thanks for sharing this!
86e4dcc
to
665f882
Compare
af62831
to
6aaf4ac
Compare
Ok, I've cleaned this up enough to be ready for an initial review. This PR just lays the groundwork -- I'm not writing the complete porting of docs over to RTD in this PR. What I'm going to do is:
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
In general this looks great! looking forward to better docs. Maybe linking #1332 should be mentioned in the PR description?
Done |
938e8b2
to
6964be2
Compare
…es_python into rtd
…ild/rules_python into rtd
…bazelbuild/rules_python into rtd
…om:443/bazelbuild/rules_python into rtd
…ithub.com:443/bazelbuild/rules_python into rtd
…//ssh.github.com:443/bazelbuild/rules_python into rtd
This lays the groundwork for using Sphinx to generate user-facing documentation and
having it published on readthedocs. It integrates with Bazel Stardoc to generate
MyST-flavored Markdown that Sphinx can process.
There are 4 basic pieces that are glued together:
sphinx_docs
: This rule invokes Sphinx to generate e.g. html, latex, etcsphinx_stardoc
: This rule invokes Stardoc to generate MyST-flavored Markdownthat Sphinx can process
sphinx_build_binary
: This rule defines the Sphinx executable with any necessarydependencies (e.g. Sphinx extensions, like MyST) to process the docs in (1)
readthedocs_install
: This rule does the necessary steps to build the docs andput them into the location the readthedocs build process expects. This is basically
just
cp -r
, but its cleaner to hide it behind abazel run
command than haveto put various shell in the readthedocs yaml config.
bzlmod and Stardoc.
Work towards #1332, #1484