Skip to content

Commit 23a6d71

Browse files
WorkerPantsWorkerPants
authored
Update docs site for version 2.26.0.dev7 (#334)
Docs from https://github.com/pantsbuild/pants/releases/tag/release_2.26.0.dev7
1 parent 27ab947 commit 23a6d71

File tree

202 files changed

+2401
-2190
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

202 files changed

+2401
-2190
lines changed

‎docs/docs/docker/_category_.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
11
{
22
"label": "Docker",
3-
"position": 9
3+
"position": 8
44
}

‎docs/docs/go/_category_.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
11
{
22
"label": "Go",
3-
"position": 6
3+
"position": 5
44
}

‎docs/docs/jvm/_category_.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
11
{
22
"label": "JVM",
3-
"position": 7
3+
"position": 6
44
}

‎docs/docs/kubernetes/_category_.json

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
{
2+
"label": "Kubernetes",
3+
"position": 9
4+
}

‎docs/docs/kubernetes/index.mdx

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
---
2+
title: Kubernetes Overview
3+
sidebar_position: 999
4+
---
5+
6+
---
7+
8+
:::caution Kubernetes support is in alpha stage
9+
Pants is currently building support for Kubernetes. Simple use cases might be
10+
supported, but many options are missing.
11+
12+
Please share feedback for what you need to use Pants with your Kubernetes queries by
13+
either [opening a GitHub
14+
issue](https://github.com/pantsbuild/pants/issues/new/choose) or [joining our
15+
Slack](/community/getting-help)!
16+
:::
17+
18+
## Initial setup
19+
20+
First, activate the relevant backend in `pants.toml`:
21+
22+
```toml title="pants.toml"
23+
[GLOBAL]
24+
backend_packages = [
25+
...
26+
"pants.backend.experimental.k8s",
27+
...
28+
]
29+
```
30+
31+
The Kubernetes backend adds [`k8s_source`](../../reference/targets/k8s_source.mdx) and
32+
[`k8s_sources`](../../reference/targets/k8s_sources.mdx) target types for Kubernetes object
33+
files.
34+
35+
For example, create a file `src/k8s/webpages.yaml`:
36+
37+
```yaml title="src/k8s/webpages.yaml"
38+
---
39+
apiVersion: v1
40+
kind: ConfigMap
41+
metadata:
42+
name: webpages
43+
data:
44+
index.html: |
45+
<html>
46+
<head>Hello pants!</head>
47+
<body>Hello pants!</body>
48+
</html>
49+
```
50+
51+
Now add a `k8s_sources` target in `src/k8s/BUILD`:
52+
53+
```python title="src/k8s/BUILD"
54+
k8s_sources()
55+
```
56+
57+
## Deploying objects to a cluster
58+
59+
We'll be using a local [kind](https://kind.sigs.k8s.io/) cluster throughout the
60+
tutorial. First, spin up a cluster:
61+
62+
```bash
63+
kind create cluster
64+
```
65+
```
66+
Creating cluster "kind" ...
67+
✓ Ensuring node image (kindest/node:v1.25.3) 🖼
68+
✓ Preparing nodes 📦
69+
✓ Writing configuration 📜
70+
✓ Starting control-plane 🕹️
71+
✓ Installing CNI 🔌
72+
✓ Installing StorageClass 💾
73+
Set kubectl context to "kind-kind"
74+
```
75+
76+
Second, configure the list of available contexts in `pants.toml`:
77+
78+
```toml title="pants.toml"
79+
...
80+
81+
[k8s]
82+
available_contexts = [
83+
"kind-kind",
84+
]
85+
```
86+
87+
Third, create a deployable target `k8s_bundle` in `src/k8s/BUILD`:
88+
89+
```python title="src/k8s/BUILD"
90+
k8s_sources()
91+
k8s_bundle(
92+
name="webpages",
93+
sources=("src/k8s/webpages.yaml",),
94+
context="kind-kind",
95+
)
96+
```
97+
98+
Now you can deploy the target:
99+
100+
```bash
101+
pants experimental-deploy src/k8s:webpages
102+
```
103+
```
104+
✓ src/k8s:webpages deployed to context kind-kind
105+
```
106+
107+
note::: To prevent accidentally deploying kubernetes manifests to the wrong
108+
cluster, the context field is required on `k8s_bundle` for deployment. For
109+
deploying the same `k8s_bundle` to multiple contexts, consider using
110+
`parametrize` like `k8s_bundle(..., context=parametrize("stage", "prod"))`. For
111+
CI agents which will only have access to a single context, set the
112+
`[kubectl].pass_context` to false in `pants.toml` to have them use their
113+
default context.

‎docs/docs/python/_category_.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
11
{
22
"label": "Python",
3-
"position": 5
3+
"position": 4
44
}

‎docs/docs/shell/_category_.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
11
{
22
"label": "Shell",
3-
"position": 8
3+
"position": 7
44
}

‎docs/docs/using-pants/_category_.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
11
{
22
"label": "Using Pants",
3-
"position": 4
3+
"position": 3
44
}

‎docs/reference/build-file-symbols/__defaults__.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,6 @@ import BuildFileSymbol from "@site/src/components/reference/BuildFileSymbol";
1010

1111
Provide default field values.
1212

13-
Learn more https://www.pantsbuild.org/2.25/docs/using-pants/key-concepts/targets-and-build-files#field-default-values
13+
Learn more https://www.pantsbuild.org/2.26/docs/using-pants/key-concepts/targets-and-build-files#field-default-values
1414

1515
</BuildFileSymbol>

‎docs/reference/global-options.mdx

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -212,7 +212,7 @@ remote_provider = <RemoteProvider>`}
212212
default_repr={`reapi`}
213213
>
214214

215-
The type of provider to use, if using a remote cache and/or remote execution, See https://www.pantsbuild.org/2.25/docs/using-pants/remote-caching-and-execution for details.
215+
The type of provider to use, if using a remote cache and/or remote execution, See https://www.pantsbuild.org/2.26/docs/using-pants/remote-caching-and-execution for details.
216216

217217
Each provider supports different `remote_store_address` and (optional) `remote_execution_address` URIs.
218218

@@ -272,7 +272,7 @@ tag = [
272272
default_repr={`[]`}
273273
>
274274

275-
Include only targets with these tags (optional &#x27;+&#x27; prefix) or without these tags (&#x27;-&#x27; prefix). See https://www.pantsbuild.org/2.25/docs/using-pants/advanced-target-selection.
275+
Include only targets with these tags (optional &#x27;+&#x27; prefix) or without these tags (&#x27;-&#x27; prefix). See https://www.pantsbuild.org/2.26/docs/using-pants/advanced-target-selection.
276276

277277
</Option>
278278

@@ -332,7 +332,7 @@ build_file_prelude_globs = [
332332
default_repr={`[]`}
333333
>
334334

335-
Python files to evaluate and whose symbols should be exposed to all BUILD files. See https://www.pantsbuild.org/2.25/docs/writing-plugins/macros.
335+
Python files to evaluate and whose symbols should be exposed to all BUILD files. See https://www.pantsbuild.org/2.26/docs/writing-plugins/macros.
336336

337337
</Option>
338338

@@ -392,7 +392,7 @@ Path to a file containing PEM-format CA certificates used for verifying secure c
392392

393393
Even when using the `docker_environment` and `remote_environment` targets, this path will be read from the local host, and those certs will be used in the environment.
394394

395-
This option cannot be overridden via environment targets, so if you need a different value than what the rest of your organization is using, override the value via an environment variable, CLI argument, or `.pants.rc` file. See https://www.pantsbuild.org/2.25/docs/using-pants/key-concepts/options.
395+
This option cannot be overridden via environment targets, so if you need a different value than what the rest of your organization is using, override the value via an environment variable, CLI argument, or `.pants.rc` file. See https://www.pantsbuild.org/2.26/docs/using-pants/key-concepts/options.
396396

397397
</Option>
398398

@@ -818,7 +818,7 @@ pants_version = <str>`}
818818

819819
Use this Pants version. Note that Pants only uses this to verify that you are using the requested version, as Pants cannot dynamically change the version it is using once the program is already running.
820820

821-
If you use the `pants` script from https://www.pantsbuild.org/2.25/docs/getting-started/installing-pants, however, changing the value in your `pants.toml` will cause the new version to be installed and run automatically.
821+
If you use the `pants` script from https://www.pantsbuild.org/2.26/docs/getting-started/installing-pants, however, changing the value in your `pants.toml` will cause the new version to be installed and run automatically.
822822

823823
Run `pants --version` to check what is being used.
824824

@@ -1337,7 +1337,7 @@ An oauth token to use for gGRPC connections to `[GLOBAL].remote_execution_addres
13371337

13381338
If specified, Pants will add a header in the format `authorization: Bearer <token>`. You can also manually add this header via `[GLOBAL].remote_execution_headers` and `[GLOBAL].remote_store_headers`, or use `[GLOBAL].remote_auth_plugin` to provide a plugin to dynamically set the relevant headers. Otherwise, no authorization will be performed.
13391339

1340-
Recommendation: do not place a token directly in `pants.toml`, instead do one of: set the token via the environment variable (`PANTS_REMOTE_OAUTH_BEARER_TOKEN`), CLI option (`--remote-oauth-bearer-token`), or store the token in a file and set the option to `"@/path/to/token.txt"` to [read the value from that file](https://www.pantsbuild.org/2.25/docs/using-pants/key-concepts/options#reading-individual-option-values-from-files).
1340+
Recommendation: do not place a token directly in `pants.toml`, instead do one of: set the token via the environment variable (`PANTS_REMOTE_OAUTH_BEARER_TOKEN`), CLI option (`--remote-oauth-bearer-token`), or store the token in a file and set the option to `"@/path/to/token.txt"` to [read the value from that file](https://www.pantsbuild.org/2.26/docs/using-pants/key-concepts/options#reading-individual-option-values-from-files).
13411341

13421342
</Option>
13431343

@@ -1644,7 +1644,7 @@ Set to False if Pants should not watch the filesystem for changes. `pantsd` or `
16441644
toml_repr={`[GLOBAL]
16451645
allow_deprecated_macos_before_12 = <bool>`}
16461646
default_repr={`False`}
1647-
removal_version='2.26.0.dev0'
1647+
removal_version='2.27.0.dev0'
16481648
removal_hint={'Upgrade your operating system or write `allow_deprecated_macos_versions = ["10", "11"]` instead.'}
16491649
>
16501650

@@ -1663,7 +1663,7 @@ If you have questions or concerns about this, please reach out to us at https://
16631663
native_options_validation = <NativeOptionsValidation>`}
16641664
one_of='ignore, warning, error'
16651665
default_repr={`warning`}
1666-
removal_version='2.26.0.dev0'
1666+
removal_version='2.27.0.dev0'
16671667
removal_hint={'The legacy parser has been removed so this option has no effect.'}
16681668
>
16691669

‎docs/reference/goals/export.mdx

Lines changed: 1 addition & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -156,28 +156,7 @@ This only applies when when exporting a `mutable_virtualenv` (`symlinked_immutab
156156

157157
## Deprecated options
158158

159-
### `py_hermetic_scripts`
160-
161-
<Option
162-
cli_repr={`--[no-]export-py-hermetic-scripts`}
163-
env_repr='PANTS_EXPORT_PY_HERMETIC_SCRIPTS'
164-
toml_repr={`[export]
165-
py_hermetic_scripts = <bool>`}
166-
default_repr={`True`}
167-
removal_version='2.26.0.dev0'
168-
removal_hint={'Use `--export-py-non-hermetic-scripts-in-resolve` instead.'}
169-
>
170-
171-
When exporting a mutable virtualenv for a resolve, by default modify console script shebang lines to make them &#x22;hermetic&#x22;. The shebang of hermetic console scripts uses the python args: `-sE`:
172-
173-
- `-s` skips inclusion of the user site-packages directory,
174-
- `-E` ignores all `PYTHON*` env vars like `PYTHONPATH`.
175-
176-
Set this to false if you need non-hermetic scripts with simple python shebangs that respect vars like `PYTHONPATH`, to, for example, allow IDEs like PyCharm to inject its debugger, coverage, or other IDE-specific libs when running a script.
177-
178-
This only applies when when exporting a `mutable_virtualenv` (`symlinked_immutable_virtualenv` exports are not &#x22;full&#x22; virtualenvs because they are used internally by pants itself. Pants requires hermetic scripts to provide its reproduciblity guarantee, fine-grained caching, and other features).
179-
180-
</Option>
159+
None
181160

182161
## Related subsystems
183162

‎docs/reference/goals/fix.mdx

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -19,16 +19,16 @@ This goal runs tools that make &#x27;semantic&#x27; changes to source code, wher
1919

2020
See also:
2121

22-
- [The `fmt` goal](https://www.pantsbuild.org/2.25/reference/goals/fix will run code-editing tools that may make only
22+
- [The `fmt` goal](https://www.pantsbuild.org/2.26/reference/goals/fix will run code-editing tools that may make only
2323
syntactic changes, not semantic ones. The `fix` includes running these `fmt` tools by
2424
default (see [the `skip_formatters` option](#skip_formatters) to control this).
2525

26-
- [The `lint` goal](https://www.pantsbuild.org/2.25/reference/goals/lint) will validate code is formatted, by running these
26+
- [The `lint` goal](https://www.pantsbuild.org/2.26/reference/goals/lint) will validate code is formatted, by running these
2727
fixers and checking there&#x27;s no change.
2828

2929
- Documentation about formatters for various ecosystems, such as:
30-
[Python](https://www.pantsbuild.org/2.25/docs/python/overview/linters-and-formatters), [JVM](https://www.pantsbuild.org/jvm/java-and-scala#lint-and-format),
31-
[SQL](https://www.pantsbuild.org/2.25/docs/sql#enable-sqlfluff-linter)
30+
[Python](https://www.pantsbuild.org/2.26/docs/python/overview/linters-and-formatters), [JVM](https://www.pantsbuild.org/jvm/java-and-scala#lint-and-format),
31+
[SQL](https://www.pantsbuild.org/2.26/docs/sql#enable-sqlfluff-linter)
3232

3333
Backend: <span className="color--primary">`pants.core`</span>
3434

‎docs/reference/goals/fmt.mdx

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -19,15 +19,15 @@ This goal runs tools that make &#x27;syntactic&#x27; changes to source code, whe
1919

2020
See also:
2121

22-
- [The `fix` goal](https://www.pantsbuild.org/2.25/reference/goals/fix) will run code-editing tools that may make semantic
22+
- [The `fix` goal](https://www.pantsbuild.org/2.26/reference/goals/fix) will run code-editing tools that may make semantic
2323
changes, not just syntactic ones.
2424

25-
- [The `lint` goal](https://www.pantsbuild.org/2.25/reference/goals/lint) will validate code is formatted, by running these
25+
- [The `lint` goal](https://www.pantsbuild.org/2.26/reference/goals/lint) will validate code is formatted, by running these
2626
formatters and checking there&#x27;s no change.
2727

2828
- Documentation about formatters for various ecosystems, such as:
29-
[Python](https://www.pantsbuild.org/2.25/docs/python/overview/linters-and-formatters), [Go](https://www.pantsbuild.org/2.25/docs/go#gofmt),
30-
[JVM](https://www.pantsbuild.org/jvm/java-and-scala#lint-and-format), [Shell](https://www.pantsbuild.org/2.25/docs/shell#shfmt-autoformatter).
29+
[Python](https://www.pantsbuild.org/2.26/docs/python/overview/linters-and-formatters), [Go](https://www.pantsbuild.org/2.26/docs/go#gofmt),
30+
[JVM](https://www.pantsbuild.org/jvm/java-and-scala#lint-and-format), [Shell](https://www.pantsbuild.org/2.26/docs/shell#shfmt-autoformatter).
3131

3232
Backend: <span className="color--primary">`pants.core`</span>
3333

‎docs/reference/goals/lint.mdx

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -19,16 +19,16 @@ This goal runs tools that check code quality/styling etc, without changing that
1919

2020
See also:
2121

22-
- [The `fmt` goal](https://www.pantsbuild.org/2.25/reference/goals/fix will save the the result of formatters
22+
- [The `fmt` goal](https://www.pantsbuild.org/2.26/reference/goals/fix will save the the result of formatters
2323
(code-editing tools that make only &#x22;syntactic&#x22; changes) back to the workspace.
2424

25-
- [The `fmt` goal](https://www.pantsbuild.org/2.25/reference/goals/fix will save the the result of fixers
25+
- [The `fmt` goal](https://www.pantsbuild.org/2.26/reference/goals/fix will save the the result of fixers
2626
(code-editing tools that may make &#x22;semantic&#x22; changes too) back to the workspace.
2727

2828
- Documentation about linters for various ecosystems, such as:
29-
[Python](https://www.pantsbuild.org/2.25/docs/python/overview/linters-and-formatters), [Go](https://www.pantsbuild.org/2.25/docs/go),
30-
[JVM](https://www.pantsbuild.org/jvm/java-and-scala#lint-and-format), [Shell](https://www.pantsbuild.org/2.25/docs/shell),
31-
[Docker](https://www.pantsbuild.org/2.25/docs/docker#linting-dockerfiles-with-hadolint).
29+
[Python](https://www.pantsbuild.org/2.26/docs/python/overview/linters-and-formatters), [Go](https://www.pantsbuild.org/2.26/docs/go),
30+
[JVM](https://www.pantsbuild.org/jvm/java-and-scala#lint-and-format), [Shell](https://www.pantsbuild.org/2.26/docs/shell),
31+
[Docker](https://www.pantsbuild.org/2.26/docs/docker#linting-dockerfiles-with-hadolint).
3232

3333
Backend: <span className="color--primary">`pants.core`</span>
3434

‎docs/reference/goals/publish.mdx

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,21 @@ Config section: <span className="color--primary">`[publish]`</span>
2323

2424
## Basic options
2525

26+
### `noninteractive_process_output`
27+
28+
<Option
29+
cli_repr={`--publish-noninteractive-process-output=<ShowOutput>`}
30+
env_repr='PANTS_PUBLISH_NONINTERACTIVE_PROCESS_OUTPUT'
31+
toml_repr={`[publish]
32+
noninteractive_process_output = <ShowOutput>`}
33+
one_of='all, failed, none'
34+
default_repr={`all`}
35+
>
36+
37+
Show stdout/stderr when publishing with noninteractively. This only has an effect for those publish subsystems that support a noninteractive mode.
38+
39+
</Option>
40+
2641
### `output`
2742

2843
<Option

‎docs/reference/goals/tailor.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -53,7 +53,7 @@ key2 = val2
5353
default_repr={`{}`}
5454
>
5555

56-
A mapping from standard target type to custom type to use instead. The custom type can be a custom target type or a macro that offers compatible functionality to the one it replaces (see https://www.pantsbuild.org/2.25/docs/writing-plugins/macros).
56+
A mapping from standard target type to custom type to use instead. The custom type can be a custom target type or a macro that offers compatible functionality to the one it replaces (see https://www.pantsbuild.org/2.26/docs/writing-plugins/macros).
5757

5858
</Option>
5959

‎docs/reference/goals/update-build-files.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ pants update-build-files [args]
1515

1616
Format and fix safe deprecations in BUILD files.
1717

18-
This does not handle the full Pants upgrade. You must still manually change `pants_version` in `pants.toml` and you may need to manually address some deprecations. See https://www.pantsbuild.org/2.25/docs/releases/upgrade-tips for upgrade tips.
18+
This does not handle the full Pants upgrade. You must still manually change `pants_version` in `pants.toml` and you may need to manually address some deprecations. See https://www.pantsbuild.org/2.26/docs/releases/upgrade-tips for upgrade tips.
1919

2020
Backend: <span className="color--primary">`pants.core`</span>
2121

0 commit comments

Comments
 (0)