Streamline some goal descriptions. #10911
Conversation
The old ones contained unnecessary detail. [ci skip-rust] [ci skip-build-wheels]
| @@ -31,7 +31,7 @@ | |||
|
|
|||
|
|
|||
| class TargetTypesSubsystem(LineOriented, GoalSubsystem): | |||
| """List all the registered target types, including custom plugin types.""" | |||
| """List all registered target types.""" | |||
There was a problem hiding this comment.
Plugins are the basic way Pants works, there's no need to qualify. This might make the reader think "hm, where are plugins not included"?
| @@ -60,7 +60,7 @@ def generate_exe(self, _: Platform) -> str: | |||
|
|
|||
|
|
|||
| class CountLinesOfCodeSubsystem(GoalSubsystem): | |||
| """Count lines of code using `scc` (Succinct Code Counter, https://github.com/boyter/scc).""" | |||
| """Count lines of code.""" | |||
There was a problem hiding this comment.
Too much detail.
| @@ -29,7 +29,7 @@ class BuiltPackage: | |||
|
|
|||
|
|
|||
| class PackageSubsystem(GoalSubsystem): | |||
| """Package an asset and put in `--distdir`, such as an archive, PEX, wheel, AWS Lambda, etc.""" | |||
| """Create a distributable package.""" | |||
There was a problem hiding this comment.
The examples are unnecessary, and --distdir mention is too much detail.
There was a problem hiding this comment.
These changes all look good.
But because these descriptions end up in ./pants help and on https://www.pantsbuild.org/docs/reference-all-goals (where having more information is very, very helpful), we might want to differentiate the "first sentence" of a description from the rest, and then significantly expand the rest of the description to add more meat to each of the pages.
For example, the generated package page now looks like https://www.pantsbuild.org/docs/reference-package ... which really doesn't do enough to explain what the goal does. On the other hand, the hand written package page goes into a lot more depth: https://www.pantsbuild.org/docs/python-package-goal ... some of which is generic, and could be in here.
The old ones contained unnecessary detail.
[ci skip-rust]
[ci skip-build-wheels]