sphinxdocs: add docs; support sources from other directories #2128
+1,030
−213
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_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:sphinx_docs
could accept files from other directories was using therename_srcs
arg and manually renaming files one-by-one.sphinx_stardocs
required 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.deps
attribute andsphinx_docs_library
rule are added. The library targets collect files, andsphinx_docs
moves then into the final Sphinx sources directory.To fix (2), the
sphinx_stardoc.srcs
attribute is added, which acceptsbzl_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, thesphinx_stardoc
(singular) rule can be called directly.Also:
bzl:rule
as a cross reference lookup role