Include "provider" value for BUILD file symbols in help-all output
#20976
Comments
|
I guess this could appear in the |
huonw
added a commit
to pantsbuild/pantsbuild.org
that referenced
this issue
May 30, 2024
This adds a new section to the reference docs:
`/2.x/reference/build-file-symbols/`. This renders all the known
non-target BUILD file symbols, as indicated by the
`name_to_build_file_info` key of the `help-all` output JSON.
This JSON looks like the following, and this generation basically just
mashes it up into documentation form:
```json
"name_to_build_file_info": {
"PANTS_VERSION": {
"documentation": null,
"is_target": false,
"name": "PANTS_VERSION",
"signature": null
},
"__defaults__": {
"documentation": "Provide default field values.\n\nLearn more https://www.pantsbuild.org/2.22/docs/using-pants/key-concepts/targets-and-build-files#field-default-values",
"is_target": false,
"name": "__defaults__",
"signature": "(*args: 'SetDefaultsT', ignore_unknown_fields: 'bool' = False, ignore_unknown_targets: 'bool' = False, **kwargs) -> 'None'"
},
"__dependencies_rules__": {
"documentation": "Declare dependencies rules.",
"is_target": false,
"name": "__dependencies_rules__",
"signature": "(*args, **kwargs) -> 'None'"
},
"__dependents_rules__": {
"documentation": "Declare dependents rules.",
"is_target": false,
"name": "__dependents_rules__",
"signature": "(*args, **kwargs) -> 'None'"
},
"_generator_sources_helper": {
"documentation": null,
"is_target": true,
"name": "_generator_sources_helper",
"signature": "(**kwargs: 'Any') -> 'TargetAdaptor'"
},
"_lockfile": {
"documentation": null,
"is_target": true,
"name": "_lockfile",
"signature": "(**kwargs: 'Any') -> 'TargetAdaptor'"
},
...
```
This is a new sidebar option:
Some of these have reasonable docs:
Others do not have good docs:
I think we should land this and then separately work to improve the
documentation of each BUILD file symbol:
- pantsbuild/pants#20976
- pantsbuild/pants#20977
- pantsbuild/pants#20978
- pantsbuild/pants#20979
- pantsbuild/pants#20980
To make this work, there's two other changes required, which are done as
separate commits:
- support for back-tick code blocks, to avoid mangling them
- explicit sidebar positions, so that `BUILD file symbols` is placed
last, rather than before `Global options` (thus becoming the default)
This generates back to the first version that include that (2.16) and
involves some other changes to the code-genned docs, hence this is
targeted `automation:sync-docs`.
Fixes #212
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Is your feature request related to a problem? Please describe.
For doc generation purposes (pantsbuild/pantsbuild.org#216), it would be nice to indicate what backend a "BUILD file symbol" comes from, but that information isn't available.
We have various BUILD file symbols like
__defaults__,PANTS_VERSION,node_build_script,stevedore_namespacewhich are functions or constants that aren't targets. Currently,pants help-allshows these inname_to_build_file_info, but it has pretty minimal content:(Note that targets also appear, but are easy to filter out.)
Describe the solution you'd like
A
providervalue available for BUILD file symbols somehow, either inname_to_build_file_infoor by putting them in their own section.For example, this is what goals shows:
Describe alternatives you've considered
N/A
Additional context
objectsandcontext_aware_object_factories(including so it shows up in docsite) #14832The text was updated successfully, but these errors were encountered: