Use the whole description for ./pants help $subsystem (pantsbuild#1…

…1361)

Before, we would only render the first line of the docstring. Now, we use a `help` property to be able to safely render the entire thing - see pantsbuild#11355 for why we use a property rather than continuing to use the docstring.

Before:

```
▶ ./pants help changed
`changed` subsystem options
---------------------------

Tell Pants to detect what files and targets have changed from Git.

Config section: [changed]
```

After:

```
▶ ./pants help changed
`changed` subsystem options
---------------------------

Tell Pants to detect what files and targets have changed from Git.

See https://www.pantsbuild.org/docs/advanced-target-selection.

Config section: [changed]
```

[ci skip-rust]
[ci skip-build-wheels]

pants-plugins/internal_plugins/releases/register.py

@@ -14,9 +14,8 @@
 
 
 class PantsReleases(Subsystem):
-    """Options for Pants's release process."""
-
     options_scope = "pants-releases"
+    help = "Options for Pants's release process."
 
     @classmethod
     def register_options(cls, register):

src/python/pants/backend/awslambda/python/lambdex.py

@@ -5,9 +5,9 @@
 
 
 class Lambdex(PythonToolBase):
-    """A tool for turning .pex files into AWS Lambdas (https://github.com/wickman/lambdex)."""
-
     options_scope = "lambdex"
+    help = "A tool for turning .pex files into AWS Lambdas (https://github.com/wickman/lambdex)."
+
     default_version = "lambdex==0.1.3"
     # TODO(John Sirois): Remove when we can upgrade to a version of lambdex with
     # https://github.com/wickman/lambdex/issues/6 fixed.

src/python/pants/backend/codegen/export_codegen_goal.py

@@ -21,9 +21,8 @@
 
 
 class ExportCodegenSubsystem(GoalSubsystem):
-    """Write generated files to `dist/codegen` for use outside of Pants."""
-
     name = "export-codegen"
+    help = "Write generated files to `dist/codegen` for use outside of Pants."
 
     required_union_implementations = (GenerateSourcesRequest,)
 

src/python/pants/backend/codegen/protobuf/protoc.py

@@ -8,9 +8,9 @@
 
 
 class Protoc(TemplatedExternalTool):
-    """The protocol buffer compiler (https://developers.google.com/protocol-buffers)."""
-
     options_scope = "protoc"
+    help = "The protocol buffer compiler (https://developers.google.com/protocol-buffers)."
+
     default_version = "3.11.4"
     default_known_versions = [
         "3.11.4|darwin|8c6af11e1058efe953830ecb38324c0e0fd2fb67df3891896d138c535932e7db|2482119",

src/python/pants/backend/codegen/protobuf/python/grpc_python_plugin.py

@@ -5,9 +5,9 @@
 
 
 class GrpcPythonPlugin(TemplatedExternalTool):
-    """The grpc protobuf plugin for python."""
-
     options_scope = "grpc_python_plugin"
+    help = "The gRPC Protobuf plugin for Python."
+
     default_version = "1.32.0"
     default_known_versions = [
         "1.32.0|darwin|b2db586656463841aa2fd4aab34fb6bd3ef887b522d80e4f2f292146c357f533|6215304",

src/python/pants/backend/codegen/protobuf/python/python_protobuf_subsystem.py

@@ -13,12 +13,11 @@
 
 
 class PythonProtobufSubsystem(Subsystem):
-    """Options related to the Protobuf Python backend.
-
-    See https://www.pantsbuild.org/docs/protobuf.
-    """
-
     options_scope = "python-protobuf"
+    help = (
+        "Options related to the Protobuf Python backend.\n\nSee "
+        "https://www.pantsbuild.org/docs/protobuf."
+    )
 
     @classmethod
     def register_options(cls, register):

src/python/pants/backend/project_info/count_loc.py

@@ -20,9 +20,9 @@
 
 
 class SuccinctCodeCounter(TemplatedExternalTool):
-    """The Succinct Code Counter, aka `scc` (https://github.com/boyter/scc)."""
-
     options_scope = "scc"
+    help = "The Succinct Code Counter, aka `scc` (https://github.com/boyter/scc)."
+
     default_version = "2.12.0"
     default_known_versions = [
         "2.12.0|darwin|70b7002cd1e4541cb37b7b9cbc0eeedd13ceacb49628e82ab46332bb2e65a5a6|1842530",
@@ -60,9 +60,8 @@ def generate_exe(self, _: Platform) -> str:
 
 
 class CountLinesOfCodeSubsystem(GoalSubsystem):
-    """Count lines of code."""
-
     name = "count-loc"
+    help = "Count lines of code."
 
 
 class CountLinesOfCode(Goal):

src/python/pants/backend/project_info/dependees.py

@@ -96,9 +96,8 @@ class DependeesOutputFormat(Enum):
 
 
 class DependeesSubsystem(LineOriented, GoalSubsystem):
-    """List all targets that depend on any of the input files/targets."""
-
     name = "dependees"
+    help = "List all targets that depend on any of the input files/targets."
 
     @classmethod
     def register_options(cls, register):

src/python/pants/backend/project_info/dependencies.py

@@ -27,9 +27,8 @@ class DependencyType(Enum):
 
 
 class DependenciesSubsystem(LineOriented, GoalSubsystem):
-    """List the dependencies of the input files/targets."""
-
     name = "dependencies"
+    help = "List the dependencies of the input files/targets."
 
     @classmethod
     def register_options(cls, register):

src/python/pants/backend/project_info/filedeps.py

@@ -23,9 +23,8 @@
 
 
 class FiledepsSubsystem(LineOriented, GoalSubsystem):
-    """List all source and BUILD files a target depends on."""
-
     name = "filedeps"
+    help = "List all source and BUILD files a target depends on."
 
     @classmethod
     def register_options(cls, register):

src/python/pants/backend/project_info/filter_targets.py

@@ -26,18 +26,16 @@ class TargetGranularity(Enum):
 
 
 class FilterSubsystem(LineOriented, GoalSubsystem):
-    """Filter the input targets based on various criteria.
-
-    Most of the filtering options below are comma-separated lists of filtering criteria, with an
-    implied logical OR between them, so that a target passes the filter if it matches any of the
-    criteria in the list.  A '-' prefix inverts the sense of the entire comma-separated list, so
-    that a target passes the filter only if it matches none of the criteria in the list.
-
-    Each of the filtering options may be specified multiple times, with an implied logical AND
-    between them.
-    """
-
     name = "filter"
+    help = (
+        "Filter the input targets based on various criteria.\n\nMost of the filtering options "
+        "below are comma-separated lists of filtering criteria, with an implied logical OR between "
+        "them, so that a target passes the filter if it matches any of the criteria in the list. "
+        "A '-' prefix inverts the sense of the entire comma-separated list, so that a target "
+        "passes the filter only if it matches none of the criteria in the list.\n\nEach of the "
+        "filtering options may be specified multiple times, with an implied logical AND between "
+        "them."
+    )
 
     @classmethod
     def register_options(cls, register):

src/python/pants/backend/project_info/list_roots.py

@@ -8,9 +8,8 @@
 
 
 class RootsSubsystem(LineOriented, GoalSubsystem):
-    """List the repo's registered source roots."""
-
     name = "roots"
+    help = "List the repo's registered source roots."
 
 
 class Roots(Goal):

src/python/pants/backend/project_info/list_targets.py

@@ -11,9 +11,8 @@
 
 
 class ListSubsystem(LineOriented, GoalSubsystem):
-    """Lists all targets matching the file or target arguments."""
-
     name = "list"
+    help = "Lists all targets matching the file or target arguments."
 
     @classmethod
     def register_options(cls, register):

src/python/pants/backend/project_info/source_file_validator.py

@@ -38,9 +38,8 @@ class DetailLevel(Enum):
 
 
 class ValidateSubsystem(GoalSubsystem):
-    """Validate sources against regexes."""
-
     name = "validate"
+    help = "Validate sources against regexes."
 
     @classmethod
     def register_options(cls, register):
@@ -92,9 +91,8 @@ def from_dict(cls, d: Dict[str, Any]) -> ValidationConfig:
 
 
 class SourceFileValidation(Subsystem):
-    """Configuration for source file validation."""
-
     options_scope = "sourcefile-validation"
+    help = "Configuration for source file validation."
 
     @classmethod
     def register_options(cls, register):

src/python/pants/backend/python/dependency_inference/rules.py

@@ -33,9 +33,8 @@
 
 
 class PythonInferSubsystem(Subsystem):
-    """Options controlling which dependencies will be inferred for Python targets."""
-
     options_scope = "python-infer"
+    help = "Options controlling which dependencies will be inferred for Python targets."
 
     @classmethod
     def register_options(cls, register):

src/python/pants/backend/python/goals/coverage_py.py

@@ -95,9 +95,9 @@ def value(self) -> str:
 
 
 class CoverageSubsystem(PythonToolBase):
-    """Configuration for Python test coverage measurement."""
-
     options_scope = "coverage-py"
+    help = "Configuration for Python test coverage measurement."
+
     default_version = "coverage>=5.0.3,<5.1"
     default_entry_point = "coverage"
     register_interpreter_constraints = True

src/python/pants/backend/python/goals/setup_py.py

@@ -309,9 +309,8 @@ class FirstPartyDependencyVersionScheme(enum.Enum):
 
 
 class SetupPyGeneration(Subsystem):
-    """Options to control how setup.py is generated from a `python_distribution` target."""
-
     options_scope = "setup-py-generation"
+    help = "Options to control how setup.py is generated from a `python_distribution` target."
 
     @classmethod
     def register_options(cls, register):

src/python/pants/backend/python/lint/black/subsystem.py

@@ -8,9 +8,9 @@
 
 
 class Black(PythonToolBase):
-    """The Black Python code formatter (https://black.readthedocs.io/)."""
-
     options_scope = "black"
+    help = "The Black Python code formatter (https://black.readthedocs.io/)."
+
     default_version = "black==20.8b1"
     default_extra_requirements = ["setuptools"]
     default_entry_point = "black:patched_main"

src/python/pants/backend/python/lint/docformatter/subsystem.py

@@ -8,9 +8,9 @@
 
 
 class Docformatter(PythonToolBase):
-    """The Python docformatter tool (https://github.com/myint/docformatter)."""
-
     options_scope = "docformatter"
+    help = "The Python docformatter tool (https://github.com/myint/docformatter)."
+
     default_version = "docformatter>=1.3.1,<1.4"
     default_entry_point = "docformatter:main"
     register_interpreter_constraints = True

src/python/pants/backend/python/lint/flake8/subsystem.py

@@ -8,9 +8,9 @@
 
 
 class Flake8(PythonToolBase):
-    """The Flake8 Python linter (https://flake8.pycqa.org/)."""
-
     options_scope = "flake8"
+    help = "The Flake8 Python linter (https://flake8.pycqa.org/)."
+
     default_version = "flake8>=3.7.9,<3.9"
     default_extra_requirements = [
         "setuptools<45; python_full_version == '2.7.*'",

src/python/pants/backend/python/lint/isort/subsystem.py

@@ -8,9 +8,9 @@
 
 
 class Isort(PythonToolBase):
-    """The Python import sorter tool (https://timothycrosley.github.io/isort/)."""
-
     options_scope = "isort"
+    help = "The Python import sorter tool (https://timothycrosley.github.io/isort/)."
+
     default_version = "isort[pyproject]>=5.5.1,<5.6"
     default_extra_requirements = ["setuptools"]
     register_interpreter_constraints = True

src/python/pants/backend/python/lint/pylint/subsystem.py

@@ -9,9 +9,9 @@
 
 
 class Pylint(PythonToolBase):
-    """The PyLint linter for Python code (https://www.pylint.org/)."""
-
     options_scope = "pylint"
+    help = "The Pylint linter for Python code (https://www.pylint.org/)."
+
     default_version = "pylint>=2.4.4,<2.5"
     default_entry_point = "pylint"
 

src/python/pants/backend/python/mixed_interpreter_constraints/py_constraints.py

@@ -29,9 +29,8 @@
 
 
 class PyConstraintsSubsystem(Outputting, GoalSubsystem):
-    """Determine what Python interpreter constraints are used by files/targets."""
-
     name = "py-constraints"
+    help = "Determine what Python interpreter constraints are used by files/targets."
 
     @classmethod
     def register_options(cls, register) -> None:

src/python/pants/backend/python/subsystems/ipython.py

@@ -5,9 +5,9 @@
 
 
 class IPython(PythonToolBase):
-    """The IPython enhanced REPL (https://ipython.org/)."""
-
     options_scope = "ipython"
+    help = "The IPython enhanced REPL (https://ipython.org/)."
+
     default_version = "ipython==7.16.1"  # The last version to support Python 3.6.
     default_entry_point = "IPython:start_ipython"
 

src/python/pants/backend/python/subsystems/pytest.py

@@ -8,9 +8,8 @@
 
 
 class PyTest(Subsystem):
-    """The pytest Python test framework (https://docs.pytest.org/)."""
-
     options_scope = "pytest"
+    help = "The pytest Python test framework (https://docs.pytest.org/)."
 
     @classmethod
     def register_options(cls, register):

src/python/pants/backend/python/subsystems/python_native_code.py

@@ -10,9 +10,8 @@
 
 
 class PythonNativeCode(Subsystem):
-    """Options for building native code using Python, e.g. when resolving distributions."""
-
     options_scope = "python-native-code"
+    help = "Options for building native code using Python, e.g. when resolving distributions."
 
     @classmethod
     def register_options(cls, register):

src/python/pants/backend/python/subsystems/setuptools.py

@@ -5,11 +5,11 @@
 
 
 class Setuptools(PythonToolBase):
-    """The Python setuptools library (https://github.com/pypa/setuptools)."""
+    options_scope = "setuptools"
+    help = "The Python setuptools library (https://github.com/pypa/setuptools)."
 
     # NB: setuptools doesn't have an entrypoint, unlike most python tools.
     # We call it via a generated setup.py script.
-    options_scope = "setuptools"
     default_version = "setuptools>=50.3.0,<50.4"
     default_extra_requirements = ["wheel==0.35.1"]
     register_interpreter_constraints = True

src/python/pants/backend/python/target_types.py

@@ -71,9 +71,8 @@ def value_or_global_default(self, python_setup: PythonSetup) -> Tuple[str, ...]:
 
 
 class PexBinaryDefaults(Subsystem):
-    """Default settings for creating PEX executables."""
-
     options_scope = "pex-binary-defaults"
+    help = "Default settings for creating PEX executables."
 
     @classmethod
     def register_options(cls, register):

src/python/pants/backend/python/typecheck/mypy/subsystem.py

@@ -9,9 +9,9 @@
 
 
 class MyPy(PythonToolBase):
-    """The MyPy Python type checker (http://mypy-lang.org/)."""
-
     options_scope = "mypy"
+    help = "The MyPy Python type checker (http://mypy-lang.org/)."
+
     default_version = "mypy==0.782"
     default_entry_point = "mypy"
     # See `mypy/rules.py`. We only use these default constraints in some situations. Technically,

src/python/pants/backend/python/util_rules/pex_cli.py

@@ -33,10 +33,10 @@
 
 
 class PexBinary(TemplatedExternalTool):
-    """The PEX (Python EXecutable) tool (https://github.com/pantsbuild/pex)."""
-
     options_scope = "download-pex-bin"
     name = "pex"
+    help = "The PEX (Python EXecutable) tool (https://github.com/pantsbuild/pex)."
+
     default_version = "v2.1.24"
     default_url_template = "https://github.com/pantsbuild/pex/releases/download/{version}/pex"