feat(sphinxdocs): make SphinxDocsLibraryInfo provider public - #4041
feat(sphinxdocs): make SphinxDocsLibraryInfo provider public#4041JoHoenk wants to merge 1 commit into
Conversation
There was a problem hiding this comment.
Pull request overview
This PR exposes SphinxDocsLibraryInfo as a public Starlark entry point so custom rules can supply documentation inputs to sphinx_docs/sphinx_docs_library without depending on the private rule implementation, and adds a regression test proving the public provider works end-to-end.
Changes:
- Add a new public
//sphinxdocs:sphinx_docs_library_info.bzlre-export forSphinxDocsLibraryInfo. - Add a custom test rule that returns
SphinxDocsLibraryInfo, and extend the Sphinx output test to verify the generated HTML is produced viadeps. - Wire the new
.bzlintobzl_librarytargets and Sphinx stardocs generation, and add a news entry.
Reviewed changes
Copilot reviewed 8 out of 8 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| sphinxdocs/tests/sphinx_docs/sphinx_docs_output_test.py | Adds a test asserting output contains HTML generated from docs provided via the public provider. |
| sphinxdocs/tests/sphinx_docs/defs.bzl | Introduces custom_docs_library test rule that returns SphinxDocsLibraryInfo. |
| sphinxdocs/tests/sphinx_docs/BUILD.bazel | Hooks custom_docs_library into sphinx_docs(deps=...) and registers the rule in the package. |
| sphinxdocs/sphinxdocs/sphinx_docs_library_info.bzl | New public .bzl entry point re-exporting the provider from the private implementation. |
| sphinxdocs/sphinxdocs/private/sphinx_docs_library_info.bzl | Clarifies provider field documentation around transitive semantics. |
| sphinxdocs/sphinxdocs/BUILD.bazel | Exposes a new public bzl_library target for the provider entry point. |
| sphinxdocs/docs/BUILD.bazel | Ensures stardocs generation includes the new public provider entry point. |
| news/sphinx_docs_library_info.added.md | Adds release note announcing the provider as public API. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| (sphinxdocs) The `SphinxDocsLibraryInfo` provider is now public API and can be | ||
| loaded from `//sphinxdocs:sphinx_docs_library_info.bzl`. This allows custom | ||
| rules to provide doc files to `sphinx_docs` and `sphinx_docs_library` without | ||
| depending on the `sphinx_docs_library` rule implementation. |
rickeylev
left a comment
rickeylev
left a comment
There was a problem hiding this comment.
Thanks for this. This mostly LGTM.
May I ask what sort of customized logic you are needed to implement? I'm just curious to see if there's something to consider adding to the sphinx_docs_library rule.
There was a problem hiding this comment.
We don't do news files for sphinxdocs, so go ahead and remove this.
| @@ -24,7 +24,12 @@ is prepended. | |||
| :type: depset[struct] | |||
There was a problem hiding this comment.
Since we're making this public, lets more formally define the type be:
- Define a SphinxDocsFileset provider with fields (a provider is used for memory efficiency; it does dict key sharing)
- Change the annotation here to
depset[SphinxDocsFileset] - Update the plain struct(...) calls to SphinxDocsFileset
| @@ -0,0 +1,50 @@ | |||
| # Copyright 2026 The Bazel Authors. All rights reserved. | |||
There was a problem hiding this comment.
I'm assuming you aren't a member of the Bazel organization who is contributing the code on behalf of them and asserting their copyright, so please remove the copyright text here
| strip_prefix = entry.strip_prefix, | ||
| transitive = depset( | ||
| direct = [entry], | ||
| transitive = [d[SphinxDocsLibraryInfo].transitive for d in ctx.attr.deps], |
There was a problem hiding this comment.
Lets also create a merge() function to insulate callers from having to hard-code the fields that get copied over.
Custom rules that produce doc files for sphinx_docs currently must depend on the private sphinx_docs_library rule implementation, since SphinxDocsLibraryInfo lives under sphinxdocs/private. Expose it via //sphinxdocs:sphinx_docs_library_info.bzl so custom rules can supply docs without that dependency. * Define a SphinxDocsFileset provider for the entries of the transitive field, so it types as depset[SphinxDocsFileset] instead of depset[struct]. * Add create_sphinx_docs_library_info(), which builds the provider from direct files plus deps, so callers don't require any inside knowledge. * Add a custom_docs_library test rule and output tests verifying a non-sphinx_docs_library rule can supply docs to sphinx_docs through the public provider, both directly and via deps
7892e2c to
fe291bf
Compare
Thanks a lot for the quick review and your interest! So reason behind it is that currently we are developing rules_score which is basically a bazel framework for generating software in a safety reated context. This means that we are structuring our software into "dependable elements" which include both code and safety documentation. And there we want to build a sphinx documentation per dependable element. A dependable element itself however can also depend on another dependable element (with its own sphinx documenation). So that we now can wire it together in sphinx we already load from the private path the SphinxDocsLibraryInfo and we would like to make this now a (stable) public api. Also for our case one monolithic sphinx_docs (with its one big source tree) is really an issue for scaleability, as the complete Sphinx Build - including the deps - will be rebuild due to one tiny change. That´s why we implemented smaller scale sphinx invocations (per dependable element) which we then merge afterwards in a sphinx module. |
Custom rules that produce doc files for sphinx_docs currently must depend on the private sphinx_docs_library rule implementation, since SphinxDocsLibraryInfo lives under sphinxdocs/private. Expose it via //sphinxdocs:sphinx_docs_library_info.bzl so custom rules can supply docs without that dependency.
Add a custom_docs_library test rule and output test verifying a non-sphinx_docs_library rule can supply docs to sphinx_docs through the public provider.