| commit | c7defbcd1181d30762632deb3b21e8a3a58f28a1 | [log] [tgz] |
|---|---|---|
| author | Richard Levasseur <rlevasseur@google.com> | Wed May 22 18:44:25 2024 -0700 |
| committer | GitHub <noreply@github.com> | Thu May 23 01:44:25 2024 +0000 |
| tree | cd2ef031ec0d660954429ab10982597695229bea | |
| parent | 66550eca4ae9d94be3a32da86e60a54cba13cf74 [diff] |
docs: implement Starlark domain plugin for Sphinx (#1909)
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.
* Resolution of cross-references is much smarter and customizable.
Instead of relying
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.
This repository is the home of the core Python rules -- py_library, py_binary, py_test, py_proto_library, and related symbols that provide the basis for Python support in Bazel. It also contains package installation rules for integrating with PyPI and other indices.
Documentation for rules_python is at https://rules-python.readthedocs.io and in the Bazel Build Encyclopedia.
Examples live in the examples directory.
Currently, the core rules build into the Bazel binary, and the symbols in this repository are simple aliases. However, we are migrating the rules to Starlark and removing them from the Bazel binary. Therefore, the future-proof way to depend on Python rules is via this repository. SeeMigrating from the Bundled Rules below.
The core rules are stable. Their implementation in Bazel is subject to Bazel's backward compatibility policy. Once migrated to rules_python, they may evolve at a different rate, but this repository will still follow semantic versioning.
The Bazel community maintains this repository. Neither Google nor the Bazel team provides support for the code. However, this repository is part of the test suite used to vet new Bazel releases. See How to contribute page for information on our development workflow.
For detailed documentation, see https://rules-python.readthedocs.io
See Bzlmod support for more details.