docs: implement Starlark domain plugin for Sphinx #1909
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
rickeylev
force-pushed
the
sphinx.stardoc.plugin
branch
from
52c352b
to
460331a
Compare
This implements a Sphinx plugin to support Starlark as a first-class
domain in Sphinx. A Starlark domain allows writing object descriptions
directly using Sphinx's object markup language, which allows better
integration with cross references, understanding and distinguishing
types, rendering information about things, and referencing types
from other projects.
Note that this doesn't affect the docs today because the
proto_to_markdown tool is still generating regular markdown; updating
that to generate Sphinx domain markdown will be done separately.
Summary of features:
* Types and arguments can be documented using Python syntax, e.g.
`list[str]` This includes unions, generics, and custom types. Each
component of the type expression is linked and cross referenced
appropriately. Each object can have its approprate pieces documented
and defined (e.g. a rule can have attributes, attributes can have
their defaults etc documented, etc)
* An index of Starlark objects is generated automatically. This makes
it easy, for example, to find the rules that have a particular
attribute.
* The following objects can be documented: functions, methods, rules,
repository rules, providers, aspects, bzlmod extensions, tag classes,
targets, flags, and attributes/fields of the aforementioned objects.
* Arbitary docs can cross reference to Starlark types. e.g., a manually
written "Getting Started" doc can write `{bzl:obj}PyInfo.some_field` and
it will automatically link to the appropriate API docs.
rickeylev
force-pushed
the
sphinx.stardoc.plugin
branch
from
460331a
to
271be5f
Compare
aignas
approved these changes
May 22, 2024
sphinxdocs/private/sphinx.bzl
Outdated
| @@ -273,6 +278,7 @@ def _run_sphinx(ctx, format, source_path, inputs, output_prefix): | |||
| mnemonic = "SphinxBuildDocs", | |||
| progress_message = "Sphinx building {} for %{{label}}".format(format), | |||
| env = env, | |||
| execution_requirements = {"no-sandbox": ""}, | |||
There was a problem hiding this comment.
Oops, debugging stuff left over. Removed.
|
|
||
| # Make a //foo:bar.bzl convert to foo.bar, not .foo.bar | ||
| if label.startswith("//"): | ||
| label = label.lstrip("/") |
There was a problem hiding this comment.
Technically you can have dots in the repo name, so this may break or have degenerate cases.
There was a problem hiding this comment.
Ahhh, good point. Directories and files could have dots in them, too.
I've added a TODO for this for now. I think I'll change the internal representation to use @repo//file%symbol notation instead. The dotted notation grew out of originally only having within-same-file references, but it didn't evolve well once targets became cross-referencable, and I found it more natural to write the @repo//foo:bar%baz in docs rather than repo.foo.bar.baz.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
This implements a Sphinx plugin to support Starlark as a first-class domain in Sphinx.
A Starlark domain allows writing object descriptions directly using Sphinx's object
markup language, which allows better integration with cross references, understanding
and distinguishing types, rendering information about things, and referencing types
from other projects.
Note that this doesn't affect the docs today because the proto_to_markdown tool is
still generating regular markdown; updating that to generate Sphinx domain markdown
will be done separately.
Summary of features:
list[str]This includesunions, generics, and custom types. Each component of the type expression is linked and
cross referenced appropriately. Each object can have its approprate pieces documented and
defined (e.g. a rule can have attributes, attributes can have their defaults etc
documented, etc)
to find the rules that have a particular attribute.
providers, aspects, bzlmod extensions, tag classes, targets, flags, and
attributes/fields of the aforementioned objects.
Started" doc can write
{bzl:obj}PyInfo.some_fieldand it will automatically link tothe appropriate API docs.
Markdown's link resolution rules, the Sphinx's crossreference resolution hooks are
used. This allows more concise references (e.g., just a rule's base name), distinguishing
a particular object type (e.g. a function vs rule), or referring to an absolute object.