Include provider info in help output for subsystems and target types. #13993

kaos · 2021-12-27T14:55:31Z

Example output:

$ ./pants help docker
`docker` subsystem options
--------------------------

Options for interacting with Docker.
 
Provider: pants.backend.experimental.docker
Config section: [docker]
 
  --docker-registries="{'key1': val1, 'key2': val2, ...}"
  PANTS_DOCKER_REGISTRIES
  registries
...

$ ./pants help docker_image
`docker_image` target
---------------------

The `docker_image` target describes how to build and tag a Docker image.

[...]

Provider: pants.backend.experimental.docker
Valid fields:

dependencies
    type: Iterable[str] | None
    default: None
    Addresses to other targets that this target depends on, e.g. ['helloworld/subdir:lib'].
...

# Rust tests and lints will be skipped. Delete if not intended. [ci skip-rust]

Eric-Arellano

This is awesome! Thanks.

I think this is really useful for the docsite, but I'm not as sure if it's useful for CLI output. With the CLI, you'll only be seeing the help message in the first place if that backend was activated. Wdyt?

I'm wondering if we only want to provide this information in ./pants help-all (JSON), and then in a followup we update our generate_docs.py script to render this info in the docs but we leave it out of ./pants help for now.

--

Another thing to consider is "plugin" fields, like how skip_flake8 is only registered if you use pants.backend.python.lint.flake8, even though the python_source target is registered by pants.backend.python. It would be sweet to store the backend for each Field, so that we can render the backend if its backend != the backend of the original target.

src/python/pants/help/help_formatter.py

kaos · 2021-12-27T19:20:56Z

I think this is really useful for the docsite, but I'm not as sure if it's useful for CLI output.

Yeah, I thought the docsite generation could come as a follow up. But I still think this is useful from the CLI, either to tell which backend to disable if you want to get rid of some feature, or perhaps more importantly, to identify if a feature comes from a certain plugin or if it is a core pants feature loaded with a backend.

Consider an in-house developed company plugin for pants. Those employees that are not well acquainted with Pants could have a hard time telling which features are added by the plugin and which are core pants features. This helps answer that (and is my motivating use case, actually :P )

kaos · 2021-12-27T19:22:01Z

Another thing to consider is "plugin" fields, like how skip_flake8 is only registered ...

Oh, good point. Love it, will see what can be done here :)

[ci skip-rust]

# Rust tests and lints will be skipped. Delete if not intended. [ci skip-rust]

…ource [ci skip-rust]

kaos · 2021-12-27T21:27:32Z

@Eric-Arellano ok, we didn't track the providers for rules, so had to add that in too... but now we get this nice output:

$ ./pants help python_distribution
22:24:04.09 [INFO] Initializing scheduler...
22:24:04.58 [INFO] Scheduler initialized.

`python_distribution` target
----------------------------

A publishable Python setuptools distribution (e.g. an sdist or wheel).

See https://www.pantsbuild.org/v2.9/docs/python-distributions.


Provider: pants.backend.python
Valid fields:

[...]

repositories
    type: Iterable[str] | None
    default: None
    plugin: pants.backend.experimental.python
    List of URL addresses or Twine repository aliases where to publish the Python package.
    
    Twine is used for publishing Python packages, so the address to any kind of repository that Twine supports may be used here.
    
    Aliases are prefixed with `@` to refer to a config section in your Twine configuration, such as a `.pypirc` file. Use `@pypi` to upload to the public PyPi repository, which is the default when using Twine directly.

sdist
    type: bool
    default: True
    Whether to build an sdist for the distribution.

sdist_config_settings
    type: Dict[str, Iterable[str]] | None
    default: None
    PEP-517 config settings to pass to the build backend when building an sdist.

skip_twine
    type: bool
    default: False
    plugin: pants.backend.experimental.python
    If true, don't publish this target's packages using Twine.

stuhood · 2021-12-27T21:51:29Z

Haven't looked at the details, but this is really awesome both for the CLI, and for the docsite. Thanks @kaos!

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

# Rust tests and lints will be skipped. Delete if not intended. [ci skip-rust] # Building wheels and fs_util will be skipped. Delete if not intended. [ci skip-build-wheels]

kaos · 2021-12-28T09:58:43Z

Tweaked the wording slightly:

$ ./pants help python_distribution

`python_distribution` target
----------------------------

A publishable Python setuptools distribution (e.g. an sdist or wheel).

See https://www.pantsbuild.org/v2.9/docs/python-distributions.


Activated by pants.backend.python
Valid fields:

dependencies
[...]
skip_twine
    from: pants.backend.experimental.python
    type: bool
    default: False

    If true, don't publish this target's packages using Twine.

[...]

Also added a separating line between the field headers and the description, to make it more readable, imo.

Eric-Arellano

My favorite change of 2022 thus far 🎉😅

Eric-Arellano · 2022-01-05T17:25:48Z

src/python/pants/help/help_printer.py

            print(self.maybe_cyan(f"{indent}type: {field.type_hint}"))
            print(self.maybe_cyan(f"{indent}{required_or_default}"))
            if field.description:
                formatted_desc = "\n".join(
                    hard_wrap(field.description, indent=len(indent), width=self._width)
                )
-                print(formatted_desc)
+                print("\n" + formatted_desc)


Good change.

Include provider info in help output for subsystems and target types.

c238ddf

# Rust tests and lints will be skipped. Delete if not intended. [ci skip-rust]

kaos requested a review from Eric-Arellano December 27, 2021 14:55

Eric-Arellano reviewed Dec 27, 2021

View reviewed changes

src/python/pants/help/help_formatter.py Outdated Show resolved Hide resolved

kaos added 3 commits December 27, 2021 21:20

Merge branch 'main' into help_info_backend_source

e6c0c64

[ci skip-rust]

track plugin fields providers.

d246723

# Rust tests and lints will be skipped. Delete if not intended. [ci skip-rust]

Merge remote-tracking branch 'upstream/main' into help_info_backend_s…

debb119

…ource [ci skip-rust]

kaos added 2 commits December 28, 2021 10:25

Merge branch 'main' into help_info_backend_source

4598ae6

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

cleanup, fix tests.

7f7e0e4

# Rust tests and lints will be skipped. Delete if not intended. [ci skip-rust] # Building wheels and fs_util will be skipped. Delete if not intended. [ci skip-build-wheels]

kaos added 2 commits January 5, 2022 14:02

Merge branch 'main' into help_info_backend_source

733cd71

Add tests for provider info in cli help output.

0de52e0

kaos requested a review from Eric-Arellano January 5, 2022 13:48

kaos mentioned this pull request Jan 5, 2022

Help api types #14081

Merged

Eric-Arellano approved these changes Jan 5, 2022

View reviewed changes

kaos merged commit 2d12f66 into pantsbuild:main Jan 5, 2022

kaos deleted the help_info_backend_source branch January 5, 2022 17:36

kaos mentioned this pull request May 28, 2022

Add API types and rules to cli help info #14227

Merged

huonw mentioned this pull request Dec 12, 2022

docs: goal associated with multiple backends only lists one #17772

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Include provider info in help output for subsystems and target types. #13993

Include provider info in help output for subsystems and target types. #13993

kaos commented Dec 27, 2021

Eric-Arellano left a comment

kaos commented Dec 27, 2021

kaos commented Dec 27, 2021

kaos commented Dec 27, 2021 •

edited

Loading

stuhood commented Dec 27, 2021

kaos commented Dec 28, 2021

Eric-Arellano left a comment

Eric-Arellano Jan 5, 2022

Include provider info in help output for subsystems and target types. #13993

Include provider info in help output for subsystems and target types. #13993

Conversation

kaos commented Dec 27, 2021

Eric-Arellano left a comment

Choose a reason for hiding this comment

kaos commented Dec 27, 2021

kaos commented Dec 27, 2021

kaos commented Dec 27, 2021 • edited Loading

stuhood commented Dec 27, 2021

kaos commented Dec 28, 2021

Eric-Arellano left a comment

Choose a reason for hiding this comment

Eric-Arellano Jan 5, 2022

Choose a reason for hiding this comment

kaos commented Dec 27, 2021 •

edited

Loading