| commit | d2bd4320ec1a3d840e557f2e2848e9c4206c7a25 | [log] [tgz] |
|---|---|---|
| author | Richard Levasseur <rlevasseur@google.com> | Wed Oct 16 10:00:37 2024 -0700 |
| committer | GitHub <noreply@github.com> | Wed Oct 16 17:00:37 2024 +0000 |
| tree | d9088d92bb797ba539bd9e3ad9ad9885d910aa57 | |
| parent | ced0c109b3403911e75f36be8e9ee895ea8f0962 [diff] |
sphinxdocs: add typedef directive for documenting user-defined types (#2300) This adds support for documenting user-defined Starlark "types". Starlark doesn't have user-defined types as a first-class concept, but an equivalent can be done by using `struct` with lambdas and closures. On the documentation side, the structure of these objects can be shown by have a module-level struct with matching attributes. On the Sphinx side of things, this is simple to support (and the functionality was largely already there): it's just having a directive with other directives within it (this is the same way other languages handle it). On the Starlark side of things, its a bit more complicated. Stardoc can process a module-level struct, but essentially returns a list of `(dotted_name, object_proto)`, and it will only include object types it recognizes (e.g. functions, providers, rules, etc). To work within this limitation, the proto-to-markdown converter special cases the name "TYPEDEF" to indicate a typedef. Everything with the same prefix is then treated as a member of the typedef and nested within the generated typedef directive. Conveniently, because the "TYPEDEF" object is a function, it can then include that in the output and we get "class doc" functionality for free. This is mostly motivated by converting rules_testing to use sphinxdocs. While rules_python has a couple user-define types (e.g. the depset/runfiles/PyInfo builders), rules_testing has dozens of such types, which makes it untenable to hand-write docs describing them all. Today, rules_testing is already mostly following the format sphinxdocs proscribes to generate its at https://rules-testing.readthedocs.io/en/latest/api/index.html, and it's worked pretty well.
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.
The core rules are stable. Their implementation is subject to Bazel's backward compatibility policy. This repository aims to 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.