-
Notifications
You must be signed in to change notification settings - Fork 541
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
docs: generate Starlark domain markup instead of regular markdown #1919
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
This switches our doc generation over to using the Starlark domain markup from the sphinx_stardoc plugin instead of using regular markdown. This allows the docs generated from code to better integrate with each other and other parts of the doc site. Overview of changes: * Makes the doc paths under the API directory more directly mirror their actual location. e.g. moves "defs.md" -> "python/defs.md". This is so the //tools doc entries have a more natural location, but can also be used for our other top-level directories. * Adds API docs for some of the well known targets we have. These aren't automatically generated, but use the Starlark domain markup, so integrate nicely with everything. * Ensures default values are parsable as Python expressions. Stardoc returns values like "<function foo>" or 'Label(*, "//bar")' in some cases for the default value of args/attrs. * Ensures function signatures don't crash doc rendering. Stardoc gives bad/incomplete information, so reconstructing the original signature of a function is tricky. * Allows references flags using leading slashes and a value, e.g. `--foo=bar`. This makes it more natural to write while cross referencing to the flag. * Implements `{any}` xref resolution. It was just totally broken before. * Adds some additional bzl files that get documented. * Adds some more Bazel external references. * Fixes some missing bzl_library dependencies. * A few minor QoL improvements to the docs dev server: * Print the serving directory when CTRL+C is received. This makes it easier to find the raw files that are being generated. * Fix an error during shutdown about an unterminated generator. * The `sphinx_stardocs.footer` arg is removed. This was always just a hack to get extra link targets into the generated bzl docs. It's no longer needed when the bzl domain is used. * Using `@repo//pkg:file.bzl%Name` syntax is supported in type expressions (e.g. `:type:` option or `{type}` role) by quoting the label. The quoting is necessary because, under the hood, the expressions are parsed as Python. * Objects directives support an `:origin-key` directive. This records the label identity that Bazel sees for an object (as from the Stardoc origin_key field). The markdown generate doesn't generate this for everything yet because some things are documented twice (e.g. py_binary in defs.bzl and py_binary.bzl), which would cause a crash (type things trying to define the same id). * Add `*` and `**` to var-args and var-kwargs in signatures. * Allow providers to be refered to using the `type` role. This allows providers to be referenced in `:type:` directives (e.g. in a provider field).
aignas
approved these changes
May 24, 2024
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The docs look much better, thanks!
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 switches our doc generation over to using the Starlark domain markup from the sphinx_stardoc plugin instead of using regular markdown. This allows the docs generated from code to better integrate with each other and other parts of the doc site.
Overview of changes:
--foo=bar
. This makes it more natural to write while cross referencing to the flag.{any}
xref resolution. It was just totally broken before.sphinx_stardocs.footer
arg is removed. This was always just a hack to get extra link targets into the generated bzl docs. It's no longer needed when the bzl domain is used.@repo//pkg:file.bzl%Name
syntax is supported in type expressions (e.g.:type:
option or{type}
role) by quoting the label. The quoting is necessary because, under the hood, the expressions are parsed as Python.:origin-key
directive. This records the label identity that Bazel sees for an object (as from the Stardoc origin_key field). The markdown generate doesn't generate this for everything yet because some things are documented twice (e.g. py_binary in defs.bzl and py_binary.bzl), which would cause a crash (type things trying to define the same id).*
and**
to var-args and var-kwargs in signatures.type
role. This allows providers to be referenced in:type:
directives (e.g. in a provider field).