search

pantsbuild / pants

The Pants Build System
https://www.pantsbuild.org
Apache License 2.0
3.35k stars 641 forks source link

Subsystems not labeled with their backend on the docsite #12523

Closed stuhood closed 2 years ago

stuhood commented 3 years ago

Labeling subsystems with their backends would make it clearer which backends needed to be enabled in order to activate certain features. It would also make it safe(r) to render experimental backends on the docsite.

Relates to #8992.

williamscs commented 3 years ago

Did you have a "smart" way (some sort of linking/labeling system that the docs tool has?) or were you just looking for a "Required Backend" heading and a link to the corresponding backend?

Eric-Arellano commented 3 years ago

I think the latter, adding something like Required backend: pants.backend.python.lint.bandit here:

Screen Shot 2021-08-18 at 6 41 47 PM

williamscs commented 3 years ago

I submitted a suggested edit to that bandit page, but I have no idea where to track it :/

Eric-Arellano commented 3 years ago

Thanks! I like the formatting you proposed:

Screen Shot 2021-08-18 at 7 13 55 PM

Unfortunately, that part of the docs is autogenerated, so it would be overwritten next time they get generated. But that's a good example of what we can aim for.

Would you have an interest in helping with the implementation? If so, we'd be really happy to write up some instructions! The first step would be starting to track which backend something comes from when subsystems and targets are registered - happy to write up some thoughts on how to do that.

williamscs commented 3 years ago

Ok, got it. Yeah, I'd like to try and contribute to whatever is a good first step. Some pointers would be great!

benjyw commented 3 years ago

https://github.com/pantsbuild/pants/pull/12623 provides the necessary data. Once that's merged, we can look at how to use the data in the reference page generation process.

benjyw commented 3 years ago

@williamscs https://github.com/pantsbuild/pants/pull/12623 is now merged, and provides the data structures with the necessary data. If you'd like to take a whack at actually applying the data to the generated reference pages, we're happy to provide pointers!

benjyw commented 3 years ago

The main file of interest is https://github.com/pantsbuild/pants/blob/main/src/python/pants/help/help_info_extracter.py , which extracts data into an AllHelpInfo class . We'd want to augment that class with this new data.

Then, it's pretty easy to find the parts of the codebase that use AllHelpInfo to generate reference pages, as well as terminal help text.

kaos commented 2 years ago
image

https://github.com/pantsbuild/pants/pull/14126