sphinxdocs: add docs; support sources from other directories#2128
Merged
rickeylev merged 3 commits intobazel-contrib:mainfrom Aug 19, 2024
Merged
sphinxdocs: add docs; support sources from other directories#2128rickeylev merged 3 commits intobazel-contrib:mainfrom
rickeylev merged 3 commits intobazel-contrib:mainfrom
Conversation
7831f42 to
ab91e92
Compare
Documents how to use Sphinx syntax when writing docs. There's a variety of features the `sphinx_bzl` plugin enables, but without docs, they're somewhat hard to discover and figure out how to use. Because sphinxdocs is almost entirely separate, adding its docs under `//sphinxdocs/docs` is a more natural fit. Unfortunately, this became very verbose, repetitive, and tedious, for two reasons: 1. The only way `sphinx_docs` could accept files from other directories was using the `rename_srcs` arg and manually renaming files one-by-one. 2. Similarly, `sphinx_stardocs` required a one-by-one mapping of each bzl file to its output file, which then had to be repeated in `rename_srcs`. To fix (1), the `sphinx_docs.deps` attribute and `sphinx_docs_library` rule are added. The library targets collect files, and `sphinx_docs` moves then into the final Sphinx sources directory. To fix (2), the `sphinx_stardoc.srcs` attribute is added, which accepts `bzl_library` targets. I noticed that, in almost all cases, the output name was simply the input name with the `.md` extension, so the rule now does that by default. For special cases, the `sphinx_stardoc` (singular) rule can be called directly. Also: * Adds `bzl:rule` as a cross reference lookup role * Removes some defunct stuff relating to the stardoc template files that aren't used anymore. * Disables warnings from the autosectionlabel extension. These were spamming warnings because CHANGELOG.md has many headers with the same name. * Adds more entries to bazel inventory (all of native and ctx)
ab91e92 to
e56316a
Compare
…est ... is used in bazel 6
aignas
approved these changes
Aug 19, 2024
Collaborator
aignas
left a comment
There was a problem hiding this comment.
This is super helpful, thanks!
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Documents how to use Sphinx syntax when writing docs. There's a variety of features the
sphinx_bzlplugin enables, but without docs, they're somewhat hard to discover and figure out how to use.Because sphinxdocs is almost entirely separate, adding its docs under
//sphinxdocs/docsis a more natural fit. Unfortunately, this became very verbose, repetitive, and tedious, for two reasons:sphinx_docscould accept files from other directories was using therename_srcsarg and manually renaming files one-by-one.sphinx_stardocsrequired a one-by-one mapping of each bzl file to its output file, which then had to be repeated inrename_srcs.To fix (1), the
sphinx_docs.depsattribute andsphinx_docs_libraryrule are added. The library targets collect files, andsphinx_docsmoves then into the final Sphinx sources directory.To fix (2), the
sphinx_stardoc.srcsattribute is added, which acceptsbzl_librarytargets. I noticed that, in almost all cases, the output name was simply the input name with the.mdextension, so the rule now does that by default. For special cases, thesphinx_stardoc(singular) rule can be called directly.Also:
bzl:ruleas a cross reference lookup role