Skip to content

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

Merged
rickeylev merged 3 commits intobazel-contrib:mainfrom
rickeylev:sphinxdocs.docs
Aug 19, 2024
Merged

sphinxdocs: add docs; support sources from other directories#2128
rickeylev merged 3 commits intobazel-contrib:mainfrom
rickeylev:sphinxdocs.docs

Conversation

@rickeylev
Copy link
Copy Markdown
Collaborator

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)

@rickeylev rickeylev requested a review from aignas as a code owner August 19, 2024 04:36
@rickeylev rickeylev force-pushed the sphinxdocs.docs branch 2 times, most recently from 7831f42 to ab91e92 Compare August 19, 2024 04:43
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)
Copy link
Copy Markdown
Collaborator

@aignas aignas left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is super helpful, thanks!

@rickeylev rickeylev enabled auto-merge August 19, 2024 17:52
@rickeylev rickeylev added this pull request to the merge queue Aug 19, 2024
Merged via the queue into bazel-contrib:main with commit 13ce192 Aug 19, 2024
@rickeylev rickeylev deleted the sphinxdocs.docs branch August 19, 2024 18:31
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.

2 participants