Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs: improve documentation on Pants handling list options #16738

Conversation

alexey-tereshenkov-oxb
Copy link
Contributor

@alexey-tereshenkov-oxb alexey-tereshenkov-oxb commented Sep 1, 2022

This PR explains how to override/complement any list values that may have been provided in lower-precedence sources. Current documentation page is here.

For example, having

[coverage-py]
report = ["xml"]

and running

./pants test --use-coverage --coverage-py-report=html ::
...
Wrote xml coverage report to `dist/coverage_results`
Wrote html coverage report to `dist/coverage_results`

I found this behaviour not obvious, hence the PR.

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

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

@Eric-Arellano Eric-Arellano left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks!

Comment on lines +209 to +219
You can append elements to any existing elements that may have been defined in lower-precedence sources. In this example, having the config file above, there will be a list of three elements at the runtime:

```bash
./pants --scope-listopt=baz
```

It is also possible to override any existing list values provided. In this example, having the config file above, there will be a list of one element at the runtime:

```bash
./pants --scope-listopt="['baz']"
```
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe instead of putting this in the "Config file section", move it up a few lines in the "Command line flags" section? We already explain the difference between [] vs implicit add, only don't do a good job at it. Your explanation is better.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like it better in the "Config file entries" section because the example is specifically for the overriding an existing config file. If I move it elsewhere, I have to move the pants.toml contents as well :/ WDYT?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How about on line 198, you say:

Appending will add to any values from lower-precedence sources, such as config files (pants.toml) and possibly Pants's default. Otherwise, using [] will override any lower-precedence sources.

--

because the example is specifically for the overriding an existing config file. If I move it elsewhere, I have to move the pants.toml contents as well

I'm not sure the example would be necessary?

stuhood pushed a commit that referenced this pull request Nov 19, 2022
Resurrection of #16738

---



This PR explains how to override/complement any list values that may have been provided in lower-precedence sources. Current documentation page is here.

For example, having

```
[coverage-py]
report = ["xml"]
```

and running

```
./pants test --use-coverage --coverage-py-report=html ::
...
Wrote xml coverage report to `dist/coverage_results`
Wrote html coverage report to `dist/coverage_results`
```

I found this behaviour not obvious (thinking that only the HTML report will be produced), hence the PR.

[ci skip-rust]
[ci skip-build-wheels]
benjyw pushed a commit to benjyw/pants that referenced this pull request Jan 23, 2023
Resurrection of pantsbuild#16738

---



This PR explains how to override/complement any list values that may have been provided in lower-precedence sources. Current documentation page is here.

For example, having

```
[coverage-py]
report = ["xml"]
```

and running

```
./pants test --use-coverage --coverage-py-report=html ::
...
Wrote xml coverage report to `dist/coverage_results`
Wrote html coverage report to `dist/coverage_results`
```

I found this behaviour not obvious (thinking that only the HTML report will be produced), hence the PR.

[ci skip-rust]
[ci skip-build-wheels]
AlexTereshenkov added a commit to AlexTereshenkov/pants that referenced this pull request Jan 23, 2023
Resurrection of pantsbuild#16738

---



This PR explains how to override/complement any list values that may have been provided in lower-precedence sources. Current documentation page is here.

For example, having

```
[coverage-py]
report = ["xml"]
```

and running

```
./pants test --use-coverage --coverage-py-report=html ::
...
Wrote xml coverage report to `dist/coverage_results`
Wrote html coverage report to `dist/coverage_results`
```

I found this behaviour not obvious (thinking that only the HTML report will be produced), hence the PR.

[ci skip-rust]
[ci skip-build-wheels]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants