commit 13ce1927b4ae03eb9b09542cd04ef2f5f0c1fd3e
author Richard Levasseur <rlevasseur@google.com> Mon Aug 19 11:08:38 2024 -0700
committer GitHub <noreply@github.com> Mon Aug 19 18:08:38 2024 +0000
tree ccc6b7d78c99ce299f8203aee412ddc8dfc1bb80
parent 425dfb0b225e4037978b32707534095daa6205dc

sphinxdocs: add docs; support sources from other directories (#2128)

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)