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 typedef directive for documenting user-defined types #2300

Merged
merged 4 commits into from
Oct 16, 2024

Conversation

rickeylev
Copy link
Collaborator

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.

@rickeylev rickeylev requested a review from aignas as a code owner October 14, 2024 22:43
@rickeylev rickeylev added this pull request to the merge queue Oct 16, 2024
@github-merge-queue github-merge-queue bot removed this pull request from the merge queue due to failed status checks Oct 16, 2024
@rickeylev rickeylev added this pull request to the merge queue Oct 16, 2024
@github-merge-queue github-merge-queue bot removed this pull request from the merge queue due to failed status checks Oct 16, 2024
@rickeylev rickeylev added this pull request to the merge queue Oct 16, 2024
Merged via the queue into bazelbuild:main with commit d2bd432 Oct 16, 2024
4 checks passed
@rickeylev rickeylev deleted the sphinxdocs.typedef branch October 18, 2024 02:11
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