Use newlines in `./pants help $target_type` by Eric-Arellano · Pull Request #11355 · pantsbuild/pants

Eric-Arellano · 2020-12-21T19:25:40Z

Newlines are important for readability.

However, we weren't preserving the newlines from target docstring because it's tricky to render correctly. Docstring is written with hard wrapping, whereas our options system uses soft wrapping (e.g. via implicit string concatenation). Because we wrap ./pants help to 96 characters, this could create weird situations where we could end up with really short lines. Instead, we decided to flatten everything into a single paragraph.

This PR changes the description to come from a class property description, rather than from the class's docstring, which allows for much tighter control of the rendering. Now, authors can limit use of \n to when it is only intentional, rather than unintentionally from their source code having hard wrapping due to line limits.

Before:

platforms
    type: Iterable[str] | None
    default: None
    The platforms the built PEX should be compatible with. This defaults to the
    current platform, but can be overridden to different platforms. You can give a
    list of multiple platforms to create a multiplatform PEX. To use wheels for
    specific interpreter/platform tags, you can append them to the platform with
    hyphens like: PLATFORM-IMPL-PYVER-ABI (e.g. "linux_x86_64-cp-27-cp27mu",
    "macosx_10.12_x86_64-cp-36-cp36m"). PLATFORM is the host platform e.g.
    "linux-x86_64", "macosx-10.12-x86_64", etc". IMPL is the Python implementation
    abbreviation (e.g. "cp", "pp", "jp"). PYVER is a two-digit string representing
    the python version (e.g. "27", "36"). ABI is the ABI tag (e.g. "cp36m",
    "cp27mu", "abi3", "none").

After:

platforms
    type: Iterable[str] | None
    default: None
    The platforms the built PEX should be compatible with.

    This defaults to the current platform, but can be overridden to different platforms. You can
    give a list of multiple platforms to create a multiplatform PEX.

    To use wheels for specific interpreter/platform tags, you can append them to the platform
    with hyphens like: PLATFORM-IMPL-PYVER-ABI (e.g. "linux_x86_64-cp-27-cp27mu",
    "macosx_10.12_x86_64-cp-36-cp36m"):

        - PLATFORM: the host platform, e.g. "linux-x86_64", "macosx-10.12-x86_64".
        - IMPL: the Python implementation abbreviation, e.g. "cp", "pp", "jp".
        - PYVER: a two-digit string representing the Python version, e.g. "27", "36".
        - ABI: the ABI tag, e.g. "cp36m", "cp27mu", "abi3", "none".

Added benefit: reclaim docstrings

Before, the docstring for targets/fields had to be user-facing, rather than developer-facing. Now, the docstring can mention the implementation.

[ci skip-rust]

# 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]

Eric-Arellano · 2020-12-21T19:27:39Z

+        '"macosx_10.12_x86_64-cp-36-cp36m"):\n\n    - PLATFORM: the host platform, e.g. '
+        '"linux-x86_64", "macosx-10.12-x86_64".\n    - IMPL: the Python implementation '
+        'abbreviation, e.g. "cp", "pp", "jp".\n    - PYVER: a two-digit string representing '
+        'the Python version, e.g. "27", "36".\n    - ABI: the ABI tag, e.g. "cp36m", '
+        '"cp27mu", "abi3", "none".'


I tweaked the formatting by adding the - list.

Eric-Arellano · 2020-12-21T19:30:12Z

 class ProvidesField(Field):
-    """An `artifact`, such as `setup_py`, that describes how to represent this target to the outside
-    world."""
+    """An `artifact` that describes how to represent this target to the outside world."""


This is still docstring as it's a note to other developers, not for end users.

Eric-Arellano · 2020-12-21T19:30:53Z

+        if hasattr(field, "description"):
+            description = field.description
+        else:
+            description = get_docstring(


A followup will deprecate using docstring rather than description.

benjyw

Nice!

# 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]

While deprecated, we want to do the right thing to avoid later deprecation warnings. # 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]

# 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]

Closes #10060. See https://www.pantsbuild.org/v2.2/docs/reference-all-targets and https://www.pantsbuild.org/v2.2/docs/reference-pex_binary. #11355 will improve the whitespace for these docs. TODOs: * Add an example BUILD file at the top with some/all of the fields. * Consider more intelligent ordering of the fields. * Document which backend the target type comes from. [ci skip-rust] [ci skip-build-wheels]

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 #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]

### Internal Changes * Fix too many line breaks for options in docs site ([#11377](#11377)) * Use more newlines in options help messages ([#11372](#11372)) * Fix some newlines not rendering correctly on docsite ([#11371](#11371)) * Fix formatting for `./pants subsystems` and `./pants targets` ([#11368](#11368)) * Simplify `generate_docs.py` to no longer require manually generating the input data ([#11363](#11363)) * Use the whole description for `./pants help $subsystem` ([#11361](#11361)) * Use newlines in `./pants help $target_type` ([#11355](#11355)) * [internal] Install rustup on the lint shards. ([#11392](#11392)) * Install Rust through global, pre-installed Rustup ([#11256](#11256)) * Revert "Add goals to run_info (#11374)" ([#11379](#11379)) * Add goals to run_info ([#11374](#11374)) * Update all rust dependencies within their declared ranges. ([#11366](#11366)) * Update to nails 0.11.0. ([#11370](#11370)) * cleanup some futures-related references ([#11360](#11360)) * [internal] Switch to toolchain pants plugin ([#11357](#11357)) * Simplify and fix the @ensure_daemon decorator. ([#11356](#11356)) * restore some try_future uses that were recently removed ([#11353](#11353)) * remove all remaining uses of futures v0.1.x (in favor of v0.3.x) ([#11352](#11352)) * Prepare the 1.30.2 release notes. ([#11351](#11351)) * remove remaining futures v0.1.x uses from fs/store and downstream callers ([#11346](#11346)) * fix Prost revision that did not get updated in prior PR ([#11345](#11345)) * add extension method for prost::Message for encoding to Bytes ([#11344](#11344)) * Stop installing Cmake, Go, and Protoc when bootstrapping Rust ([#11336](#11336)) * Automatically set the version in generate_docs.py ([#11337](#11337)) * Prepare 2.1.1. ([#11334](#11334)) * Prepare 2.0.1. ([#11333](#11333)) * Prepare the 1.30.2rc3 release notes. ([#11327](#11327)) * Prepare 2.0.1rc4 (again). ([#11323](#11323)) * Add type annotations around Subsystem class ([#11389](#11389)) * Support deprecation_start_version in help info. ([#11350](#11350)) [ci skip-rust]

Use newlines in ./pants help $target_type

83e0abc

# 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]

Eric-Arellano requested review from benjyw, gshuflin and stuhood December 21, 2020 19:25

Eric-Arellano commented Dec 21, 2020

View reviewed changes

benjyw approved these changes Dec 21, 2020

View reviewed changes

Eric-Arellano mentioned this pull request Dec 21, 2020

Generate docs references for target types #11340

Merged

Eric-Arellano added 3 commits December 21, 2020 12:53

Use help instead of description

cb1e8df

# 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]

Fix test

4cca86f

# 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]

gshuflin approved these changes Dec 21, 2020

View reviewed changes

Eric-Arellano merged commit 7e7b208 into pantsbuild:master Dec 21, 2020

Eric-Arellano deleted the soft-wrap branch December 21, 2020 21:50

gshuflin approved these changes Dec 21, 2020

View reviewed changes

Eric-Arellano mentioned this pull request Dec 22, 2020

Use the whole description for ./pants help $subsystem #11361

Merged

stuhood mentioned this pull request Dec 29, 2020

Prepare 2.2.0rc0. #11393

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Use newlines in `./pants help $target_type`#11355

Use newlines in `./pants help $target_type`#11355
Eric-Arellano merged 4 commits into
pantsbuild:masterfrom
Eric-Arellano:soft-wrap

Eric-Arellano commented Dec 21, 2020 •

edited

Loading

Uh oh!

Uh oh!

Eric-Arellano Dec 21, 2020

Uh oh!

Eric-Arellano Dec 21, 2020

Uh oh!

Eric-Arellano Dec 21, 2020

Uh oh!

benjyw left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

Eric-Arellano commented Dec 21, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Added benefit: reclaim docstrings

Uh oh!

Uh oh!

Eric-Arellano Dec 21, 2020

Choose a reason for hiding this comment

Uh oh!

Eric-Arellano Dec 21, 2020

Choose a reason for hiding this comment

Uh oh!

Eric-Arellano Dec 21, 2020

Choose a reason for hiding this comment

Uh oh!

benjyw left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Eric-Arellano commented Dec 21, 2020 •

edited

Loading