Skip to content
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

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

Merged
merged 3 commits into from
Aug 19, 2024

Conversation

rickeylev
Copy link
Contributor

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
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 added this pull request to the merge queue Aug 19, 2024
Merged via the queue into bazelbuild:main with commit 13ce192 Aug 19, 2024
4 checks passed
@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