Docs: improve documentation on Pants handling list options #16738
Conversation
# Rust tests and lints will be skipped. Delete if not intended. [ci skip-rust]
| 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']" | ||
| ``` |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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'sdefault. 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?
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]
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]
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]
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
and running
I found this behaviour not obvious, hence the PR.
[ci skip-rust]
[ci skip-build-wheels]