PANTS_VERSION BUILD file symbol has no docs
#20978
Comments
|
(I don't know if it's possible to use |
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
That's no issue, as we don't offer help for specific options, only on the subsystem level. Ooohh... but we do offer help for the env var names, which it does collide with. I forgot about that. We'd need to add some scoping to help stuff.. so you could say |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Describe the bug
The
PANTS_VERSIONconstant BUILD file symbol has no documentation:PANTS_VERSION=2.22.0.dev3 pants help-all | jq .name_to_build_file_info.PANTS_VERSIONPreferably we'd have:
documentation"signature": "Version"?Pants version
This seems to be the case since 2.18, up to the current latest version 2.22.0
OS
Both
Additional info
objectsandcontext_aware_object_factories(including so it shows up in docsite) #14832 (lots of discussion of contents in this one)The text was updated successfully, but these errors were encountered: