Update docs site for version 2.26.0.dev7 (#334)

Docs from https://github.com/pantsbuild/pants/releases/tag/release_2.26.0.dev7
pantsbuild · Mar 3, 2025 · 23a6d71 · 23a6d71
1 parent 27ab947
commit 23a6d71
Show file tree

Hide file tree

Showing 202 changed files with 2,401 additions and 2,190 deletions.
diff --git a/docs/docs/docker/_category_.json b/docs/docs/docker/_category_.json
@@ -1,4 +1,4 @@
 {
   "label": "Docker",
-  "position": 9
+  "position": 8
 }
diff --git a/docs/docs/go/_category_.json b/docs/docs/go/_category_.json
@@ -1,4 +1,4 @@
 {
   "label": "Go",
-  "position": 6
+  "position": 5
 }
diff --git a/docs/docs/jvm/_category_.json b/docs/docs/jvm/_category_.json
@@ -1,4 +1,4 @@
 {
   "label": "JVM",
-  "position": 7
+  "position": 6
 }
diff --git a/docs/docs/kubernetes/_category_.json b/docs/docs/kubernetes/_category_.json
@@ -0,0 +1,4 @@
+{
+  "label": "Kubernetes",
+  "position": 9
+}
diff --git a/docs/docs/kubernetes/index.mdx b/docs/docs/kubernetes/index.mdx
@@ -0,0 +1,113 @@
+---
+    title: Kubernetes Overview
+    sidebar_position: 999
+---
+
+---
+
+:::caution Kubernetes support is in alpha stage
+Pants is currently building support for Kubernetes. Simple use cases might be
+supported, but many options are missing.
+
+Please share feedback for what you need to use Pants with your Kubernetes queries by
+either [opening a GitHub
+issue](https://github.com/pantsbuild/pants/issues/new/choose) or [joining our
+Slack](/community/getting-help)!
+:::
+
+## Initial setup
+
+First, activate the relevant backend in `pants.toml`:
+
+```toml title="pants.toml"
+[GLOBAL]
+backend_packages = [
+  ...
+  "pants.backend.experimental.k8s",
+  ...
+]
+```
+
+The Kubernetes backend adds [`k8s_source`](../../reference/targets/k8s_source.mdx) and
+[`k8s_sources`](../../reference/targets/k8s_sources.mdx) target types for Kubernetes object
+files.
+
+For example, create a file `src/k8s/webpages.yaml`:
+
+```yaml title="src/k8s/webpages.yaml"
+---
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: webpages
+data:
+  index.html: |
+    <html>
+      <head>Hello pants!</head>
+      <body>Hello pants!</body>
+    </html>
+```
+
+Now add a `k8s_sources` target in `src/k8s/BUILD`:
+
+```python title="src/k8s/BUILD"
+k8s_sources()
+```
+
+## Deploying objects to a cluster
+
+We'll be using a local [kind](https://kind.sigs.k8s.io/) cluster throughout the
+tutorial. First, spin up a cluster:
+
+```bash
+kind create cluster
+```
+```
+Creating cluster "kind" ...
+ ✓ Ensuring node image (kindest/node:v1.25.3) 🖼 
+ ✓ Preparing nodes 📦  
+ ✓ Writing configuration 📜 
+ ✓ Starting control-plane 🕹️ 
+ ✓ Installing CNI 🔌 
+ ✓ Installing StorageClass 💾 
+Set kubectl context to "kind-kind"
+```
+
+Second, configure the list of available contexts in `pants.toml`:
+
+```toml title="pants.toml"
+...
+
+[k8s]
+available_contexts = [
+  "kind-kind",
+]
+```
+
+Third, create a deployable target `k8s_bundle` in `src/k8s/BUILD`:
+
+```python title="src/k8s/BUILD"
+k8s_sources()
+k8s_bundle(
+    name="webpages",
+    sources=("src/k8s/webpages.yaml",),
+    context="kind-kind",
+)
+```
+
+Now you can deploy the target:
+
+```bash
+pants experimental-deploy src/k8s:webpages
+```
+```
+✓ src/k8s:webpages deployed to context kind-kind
+```
+
+note::: To prevent accidentally deploying kubernetes manifests to the wrong
+cluster, the context field is required on `k8s_bundle` for deployment. For
+deploying the same `k8s_bundle` to multiple contexts, consider using
+`parametrize` like `k8s_bundle(..., context=parametrize("stage", "prod"))`. For
+CI agents which will only have access to a single context, set the
+`[kubectl].pass_context` to false in `pants.toml` to have them use their
+default context.
diff --git a/docs/docs/python/_category_.json b/docs/docs/python/_category_.json
@@ -1,4 +1,4 @@
 {
   "label": "Python",
-  "position": 5
+  "position": 4
 }
diff --git a/docs/docs/shell/_category_.json b/docs/docs/shell/_category_.json
@@ -1,4 +1,4 @@
 {
   "label": "Shell",
-  "position": 8
+  "position": 7
 }
diff --git a/docs/docs/using-pants/_category_.json b/docs/docs/using-pants/_category_.json
@@ -1,4 +1,4 @@
 {
   "label": "Using Pants",
-  "position": 4
+  "position": 3
 }
diff --git a/docs/reference/build-file-symbols/__defaults__.mdx b/docs/reference/build-file-symbols/__defaults__.mdx
@@ -10,6 +10,6 @@ import BuildFileSymbol from "@site/src/components/reference/BuildFileSymbol";
 
 Provide default field values.
 
-Learn more https://www.pantsbuild.org/2.25/docs/using-pants/key-concepts/targets-and-build-files#field-default-values
+Learn more https://www.pantsbuild.org/2.26/docs/using-pants/key-concepts/targets-and-build-files#field-default-values
 
 </BuildFileSymbol>
diff --git a/docs/reference/global-options.mdx b/docs/reference/global-options.mdx
@@ -212,7 +212,7 @@ remote_provider = <RemoteProvider>`}
   default_repr={`reapi`}
 >
 
-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.
+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.
 
 Each provider supports different `remote_store_address` and (optional) `remote_execution_address` URIs.
 
@@ -272,7 +272,7 @@ tag = [
   default_repr={`[]`}
 >
 
-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.
+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.
 
 </Option>
 
@@ -332,7 +332,7 @@ build_file_prelude_globs = [
   default_repr={`[]`}
 >
 
-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.
+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.
 
 </Option>
 
@@ -392,7 +392,7 @@ Path to a file containing PEM-format CA certificates used for verifying secure c
 
 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.
 
-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.
+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.
 
 </Option>
 
@@ -818,7 +818,7 @@ pants_version = <str>`}
 
 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.
 
-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.
+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.
 
 Run `pants --version` to check what is being used.
 
@@ -1337,7 +1337,7 @@ An oauth token to use for gGRPC connections to `[GLOBAL].remote_execution_addres
 
 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.
 
-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).
+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).
 
 </Option>
 
@@ -1644,7 +1644,7 @@ Set to False if Pants should not watch the filesystem for changes. `pantsd` or `
   toml_repr={`[GLOBAL]
 allow_deprecated_macos_before_12 = <bool>`}
   default_repr={`False`}
-  removal_version='2.26.0.dev0'
+  removal_version='2.27.0.dev0'
   removal_hint={'Upgrade your operating system or write `allow_deprecated_macos_versions = ["10", "11"]` instead.'}
 >
 
@@ -1663,7 +1663,7 @@ If you have questions or concerns about this, please reach out to us at https://
 native_options_validation = <NativeOptionsValidation>`}
   one_of='ignore, warning, error'
   default_repr={`warning`}
-  removal_version='2.26.0.dev0'
+  removal_version='2.27.0.dev0'
   removal_hint={'The legacy parser has been removed so this option has no effect.'}
 >
 

diff --git a/docs/reference/goals/export.mdx b/docs/reference/goals/export.mdx
@@ -156,28 +156,7 @@ This only applies when when exporting a `mutable_virtualenv` (`symlinked_immutab
 
 ## Deprecated options
 
-### `py_hermetic_scripts`
-
-<Option
-  cli_repr={`--[no-]export-py-hermetic-scripts`}
-  env_repr='PANTS_EXPORT_PY_HERMETIC_SCRIPTS'
-  toml_repr={`[export]
-py_hermetic_scripts = <bool>`}
-  default_repr={`True`}
-  removal_version='2.26.0.dev0'
-  removal_hint={'Use `--export-py-non-hermetic-scripts-in-resolve` instead.'}
->
-
-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`:
-
-- `-s` skips inclusion of the user site-packages directory,
-- `-E` ignores all `PYTHON*` env vars like `PYTHONPATH`.
-
-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.
-
-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).
-
-</Option>
+None
 
 ## Related subsystems
 

diff --git a/docs/reference/goals/fix.mdx b/docs/reference/goals/fix.mdx
@@ -19,16 +19,16 @@ This goal runs tools that make &#x27;semantic&#x27; changes to source code, wher
 
 See also:
 
-- [The `fmt` goal](https://www.pantsbuild.org/2.25/reference/goals/fix will run code-editing tools that may make only
+- [The `fmt` goal](https://www.pantsbuild.org/2.26/reference/goals/fix will run code-editing tools that may make only
   syntactic changes, not semantic ones. The `fix` includes running these `fmt` tools by
   default (see [the `skip_formatters` option](#skip_formatters) to control this).
 
-- [The `lint` goal](https://www.pantsbuild.org/2.25/reference/goals/lint) will validate code is formatted, by running these
+- [The `lint` goal](https://www.pantsbuild.org/2.26/reference/goals/lint) will validate code is formatted, by running these
   fixers and checking there&#x27;s no change.
 
 - Documentation about formatters for various ecosystems, such as:
-  [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),
-  [SQL](https://www.pantsbuild.org/2.25/docs/sql#enable-sqlfluff-linter)
+  [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),
+  [SQL](https://www.pantsbuild.org/2.26/docs/sql#enable-sqlfluff-linter)
 
 Backend: <span className="color--primary">`pants.core`</span>
 

diff --git a/docs/reference/goals/fmt.mdx b/docs/reference/goals/fmt.mdx
@@ -19,15 +19,15 @@ This goal runs tools that make &#x27;syntactic&#x27; changes to source code, whe
 
 See also:
 
-- [The `fix` goal](https://www.pantsbuild.org/2.25/reference/goals/fix) will run code-editing tools that may make semantic
+- [The `fix` goal](https://www.pantsbuild.org/2.26/reference/goals/fix) will run code-editing tools that may make semantic
   changes, not just syntactic ones.
 
-- [The `lint` goal](https://www.pantsbuild.org/2.25/reference/goals/lint) will validate code is formatted, by running these
+- [The `lint` goal](https://www.pantsbuild.org/2.26/reference/goals/lint) will validate code is formatted, by running these
   formatters and checking there&#x27;s no change.
 
 - Documentation about formatters for various ecosystems, such as:
-  [Python](https://www.pantsbuild.org/2.25/docs/python/overview/linters-and-formatters), [Go](https://www.pantsbuild.org/2.25/docs/go#gofmt),
-  [JVM](https://www.pantsbuild.org/jvm/java-and-scala#lint-and-format), [Shell](https://www.pantsbuild.org/2.25/docs/shell#shfmt-autoformatter).
+  [Python](https://www.pantsbuild.org/2.26/docs/python/overview/linters-and-formatters), [Go](https://www.pantsbuild.org/2.26/docs/go#gofmt),
+  [JVM](https://www.pantsbuild.org/jvm/java-and-scala#lint-and-format), [Shell](https://www.pantsbuild.org/2.26/docs/shell#shfmt-autoformatter).
 
 Backend: <span className="color--primary">`pants.core`</span>
 

diff --git a/docs/reference/goals/lint.mdx b/docs/reference/goals/lint.mdx
@@ -19,16 +19,16 @@ This goal runs tools that check code quality/styling etc, without changing that
 
 See also:
 
-- [The `fmt` goal](https://www.pantsbuild.org/2.25/reference/goals/fix will save the the result of formatters
+- [The `fmt` goal](https://www.pantsbuild.org/2.26/reference/goals/fix will save the the result of formatters
   (code-editing tools that make only &#x22;syntactic&#x22; changes) back to the workspace.
 
-- [The `fmt` goal](https://www.pantsbuild.org/2.25/reference/goals/fix will save the the result of fixers
+- [The `fmt` goal](https://www.pantsbuild.org/2.26/reference/goals/fix will save the the result of fixers
   (code-editing tools that may make &#x22;semantic&#x22; changes too) back to the workspace.
 
 - Documentation about linters for various ecosystems, such as:
-  [Python](https://www.pantsbuild.org/2.25/docs/python/overview/linters-and-formatters), [Go](https://www.pantsbuild.org/2.25/docs/go),
-  [JVM](https://www.pantsbuild.org/jvm/java-and-scala#lint-and-format), [Shell](https://www.pantsbuild.org/2.25/docs/shell),
-  [Docker](https://www.pantsbuild.org/2.25/docs/docker#linting-dockerfiles-with-hadolint).
+  [Python](https://www.pantsbuild.org/2.26/docs/python/overview/linters-and-formatters), [Go](https://www.pantsbuild.org/2.26/docs/go),
+  [JVM](https://www.pantsbuild.org/jvm/java-and-scala#lint-and-format), [Shell](https://www.pantsbuild.org/2.26/docs/shell),
+  [Docker](https://www.pantsbuild.org/2.26/docs/docker#linting-dockerfiles-with-hadolint).
 
 Backend: <span className="color--primary">`pants.core`</span>
 

diff --git a/docs/reference/goals/publish.mdx b/docs/reference/goals/publish.mdx
@@ -23,6 +23,21 @@ Config section: <span className="color--primary">`[publish]`</span>
 
 ## Basic options
 
+### `noninteractive_process_output`
+
+<Option
+  cli_repr={`--publish-noninteractive-process-output=<ShowOutput>`}
+  env_repr='PANTS_PUBLISH_NONINTERACTIVE_PROCESS_OUTPUT'
+  toml_repr={`[publish]
+noninteractive_process_output = <ShowOutput>`}
+  one_of='all, failed, none'
+  default_repr={`all`}
+>
+
+Show stdout/stderr when publishing with noninteractively. This only has an effect for those publish subsystems that support a noninteractive mode.
+
+</Option>
+
 ### `output`
 
 <Option

diff --git a/docs/reference/goals/tailor.mdx b/docs/reference/goals/tailor.mdx
@@ -53,7 +53,7 @@ key2 = val2
   default_repr={`{}`}
 >
 
-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).
+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).
 
 </Option>
 

diff --git a/docs/reference/goals/update-build-files.mdx b/docs/reference/goals/update-build-files.mdx
@@ -15,7 +15,7 @@ pants update-build-files [args]
 
 Format and fix safe deprecations in BUILD files.
 
-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.
+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.
 
 Backend: <span className="color--primary">`pants.core`</span>