Update docs site for version 2.21.0rc0 (#208)

Docs from https://github.com/pantsbuild/pants/releases/tag/release_2.21.0rc0
pantsbuild · May 20, 2024 · 3ed3dd6 · 3ed3dd6
1 parent e91e354
commit 3ed3dd6
Show file tree

Hide file tree

Showing 19 changed files with 812 additions and 720 deletions.
diff --git a/versioned_docs/version-2.21/docs/jvm/java-and-scala.mdx b/versioned_docs/version-2.21/docs/jvm/java-and-scala.mdx
@@ -117,6 +117,91 @@ To efficiently determine which symbols are provided by thirdparty code (i.e., wi
 The `packages` argument allows you to override which symbols a `jvm_artifact` provides. See the [`jvm_artifact` docs](../../reference/targets/jvm_artifact.mdx#packages) for more information.
 :::
 
+To enable better IDE integration, Pants has `jvm_artifacts` target generator to
+generate `jvm_artifact` targets for you.
+
+### `pom.xml`
+
+The `jvm_artifacts()` target generator parses a
+[`pom.xml`](https://maven.apache.org/guides/introduction/introduction-to-the-pom.html)
+to produce a `jvm_artifact` target for each `dependency` in
+`project.dependencies`.
+
+For example:
+
+```xml tab={"label":"pom.xml"}
+<project>
+  <dependencies>
+    <dependency>
+      <groupId>com.google.guava</groupId>
+      <artifactId>guava</artifactId>
+      <version>33.2.0-jre</version>
+    </dependency>
+    <dependency>
+      <groupId>org.apache.commons</groupId>
+      <artifactId>commons-lang3</artifactId>
+      <version>3.14.0</version>
+    </dependency>
+  </dependencies>
+</project>
+```
+
+```python tab={"label":"BUILD"}
+# This will generate two targets:
+#
+#  - //:reqs#guava
+#  - //:reqs#commons-lang3
+jvm_artifacts(name="reqs")
+```
+
+The above target generator is spiritually equivalent to this:
+
+```python title="BUILD"
+jvm_artifact(
+    group="com.google.guava",
+    artifact="guava",
+    version="33.2.0-jre",
+)
+jvm_artifact(
+    group="org.apache.commons",
+    artifact="commons-lang3",
+    version="3.14.0",
+)
+```
+
+To define `jvm_artifact` packages use `package_mapping` field:
+
+```python tab={"label":"BUILD"}
+jvm_artifacts(
+    name="reqs",
+    package_mapping={
+        "com.google.guava:guava": [
+            "com.google.common.**",
+        ],
+        "org.apache.commons:commons-lang3": [
+            "org.apache.commons.lang3.**",
+        ],
+    },
+)
+```
+
+```xml tab={"label":"pom.xml"}
+<project>
+  <dependencies>
+    <dependency>
+      <groupId>com.google.guava</groupId>
+      <artifactId>guava</artifactId>
+      <version>33.2.0-jre</version>
+    </dependency>
+    <dependency>
+      <groupId>org.apache.commons</groupId>
+      <artifactId>commons-lang3</artifactId>
+      <version>3.14.0</version>
+    </dependency>
+  </dependencies>
+</project>
+```
+
 ### `resource` targets
 
 To have your code [load files as "resources"](https://docs.oracle.com/javase/8/docs/technotes/guides/lang/resources.html):

diff --git a/versioned_docs/version-2.21/docs/writing-plugins/common-subsystem-tasks.mdx b/versioned_docs/version-2.21/docs/writing-plugins/common-subsystem-tasks.mdx
@@ -54,25 +54,27 @@ class FortranLintFieldSet(FieldSet):
 
 :::note Support depends on language backend of the subsystem
 Only some language backends support `pants export`. These include the Python and JVM backends. Only tools which are themselves written to use a backend with this feature can be exported. For example, a Python-based tool which operates on a different language is exportable.
-
+:::
 
 1. Make the subsystem a subclass of `ExportableTool`
 
-:::note Language backends may have done this in their Tool base class. For example, the Python backend with `PythonToolRequirementsBase` and JVM with `JvmToolBase` are already subclasses.
+    :::note Language backends may have done this in their Tool base class.
+    For example, the Python backend with `PythonToolRequirementsBase` and JVM with `JvmToolBase` are already subclasses.
+    :::
 
-```python
-from pants.backend.python.subsystems.python_tool_base import PythonToolBase
-from pants.core.goals.resolves import ExportableTool
+    ```python
+    from pants.backend.python.subsystems.python_tool_base import PythonToolBase
+    from pants.core.goals.resolves import ExportableTool
 
-class FortranLint(PythonToolBase, ExportableTool):
-    ...
-```
+    class FortranLint(PythonToolBase, ExportableTool):
+        ...
+    ```
 
 2. Register your class with a `UnionRule` with `ExportableTool`
 
-```python
-def rules():
-	return [
-		UnionRule(ExportableTool, FortranLint)
-	]
-```
+    ```python
+    def rules():
+        return [
+            UnionRule(ExportableTool, FortranLint)
+        ]
+    ```
diff --git a/versioned_docs/version-2.21/reference/help-all.json b/versioned_docs/version-2.21/reference/help-all.json
diff --git a/versioned_docs/version-2.21/reference/subsystems/google-java-format.mdx b/versioned_docs/version-2.21/reference/subsystems/google-java-format.mdx
@@ -99,7 +99,7 @@ lockfile = <str>`}
 
 Path to a lockfile used for installing the tool.
 
-Set to the string `<default>` to use a lockfile provided by Pants, so long as you have not changed the `--version` option. See https://github.com/pantsbuild/pants/blob/release_2.21.0a1/src/python/pants/backend/java/lint/google_java_format/google_java_format.default.lockfile.txt for the default lockfile contents.
+Set to the string `<default>` to use a lockfile provided by Pants, so long as you have not changed the `--version` option. See https://github.com/pantsbuild/pants/blob/release_2.21.0rc0/src/python/pants/backend/java/lint/google_java_format/google_java_format.default.lockfile.txt for the default lockfile contents.
 
 To use a custom lockfile, set this option to a file path relative to the build root, then run `pants jvm-generate-lockfiles --resolve=google-java-format`.
 

diff --git a/versioned_docs/version-2.21/reference/subsystems/jarjar.mdx b/versioned_docs/version-2.21/reference/subsystems/jarjar.mdx
@@ -100,7 +100,7 @@ lockfile = <str>`}
 
 Path to a lockfile used for installing the tool.
 
-Set to the string `<default>` to use a lockfile provided by Pants, so long as you have not changed the `--version` option. See https://github.com/pantsbuild/pants/blob/release_2.21.0a1/src/python/pants/jvm/shading/jarjar.default.lockfile.txt for the default lockfile contents.
+Set to the string `<default>` to use a lockfile provided by Pants, so long as you have not changed the `--version` option. See https://github.com/pantsbuild/pants/blob/release_2.21.0rc0/src/python/pants/jvm/shading/jarjar.default.lockfile.txt for the default lockfile contents.
 
 To use a custom lockfile, set this option to a file path relative to the build root, then run `pants jvm-generate-lockfiles --resolve=jarjar`.
 

diff --git a/versioned_docs/version-2.21/reference/subsystems/java-avro.mdx b/versioned_docs/version-2.21/reference/subsystems/java-avro.mdx
@@ -73,7 +73,7 @@ lockfile = <str>`}
 
 Path to a lockfile used for installing the tool.
 
-Set to the string `<default>` to use a lockfile provided by Pants, so long as you have not changed the `--version` option. See https://github.com/pantsbuild/pants/blob/release_2.21.0a1/src/python/pants/backend/codegen/avro/java/avro-tools.default.lockfile.txt for the default lockfile contents.
+Set to the string `<default>` to use a lockfile provided by Pants, so long as you have not changed the `--version` option. See https://github.com/pantsbuild/pants/blob/release_2.21.0rc0/src/python/pants/backend/codegen/avro/java/avro-tools.default.lockfile.txt for the default lockfile contents.
 
 To use a custom lockfile, set this option to a file path relative to the build root, then run `pants jvm-generate-lockfiles --resolve=java-avro`.
 

diff --git a/versioned_docs/version-2.21/reference/subsystems/junit.mdx b/versioned_docs/version-2.21/reference/subsystems/junit.mdx
@@ -103,7 +103,7 @@ lockfile = <str>`}
 
 Path to a lockfile used for installing the tool.
 
-Set to the string `<default>` to use a lockfile provided by Pants, so long as you have not changed the `--version` option. See https://github.com/pantsbuild/pants/blob/release_2.21.0a1/src/python/pants/jvm/test/junit.default.lockfile.txt for the default lockfile contents.
+Set to the string `<default>` to use a lockfile provided by Pants, so long as you have not changed the `--version` option. See https://github.com/pantsbuild/pants/blob/release_2.21.0rc0/src/python/pants/jvm/test/junit.default.lockfile.txt for the default lockfile contents.
 
 To use a custom lockfile, set this option to a file path relative to the build root, then run `pants jvm-generate-lockfiles --resolve=junit`.
 

diff --git a/versioned_docs/version-2.21/reference/subsystems/ktlint.mdx b/versioned_docs/version-2.21/reference/subsystems/ktlint.mdx
@@ -85,7 +85,7 @@ lockfile = <str>`}
 
 Path to a lockfile used for installing the tool.
 
-Set to the string `<default>` to use a lockfile provided by Pants, so long as you have not changed the `--version` option. See https://github.com/pantsbuild/pants/blob/release_2.21.0a1/src/python/pants/backend/kotlin/lint/ktlint/ktlint.lock for the default lockfile contents.
+Set to the string `<default>` to use a lockfile provided by Pants, so long as you have not changed the `--version` option. See https://github.com/pantsbuild/pants/blob/release_2.21.0rc0/src/python/pants/backend/kotlin/lint/ktlint/ktlint.lock for the default lockfile contents.
 
 To use a custom lockfile, set this option to a file path relative to the build root, then run `pants jvm-generate-lockfiles --resolve=ktlint`.
 

diff --git a/versioned_docs/version-2.21/reference/subsystems/openapi-generator.mdx b/versioned_docs/version-2.21/reference/subsystems/openapi-generator.mdx
@@ -73,7 +73,7 @@ lockfile = <str>`}
 
 Path to a lockfile used for installing the tool.
 
-Set to the string `<default>` to use a lockfile provided by Pants, so long as you have not changed the `--version` option. See https://github.com/pantsbuild/pants/blob/release_2.21.0a1/src/python/pants/backend/openapi/subsystems/openapi_generator.default.lockfile.txt for the default lockfile contents.
+Set to the string `<default>` to use a lockfile provided by Pants, so long as you have not changed the `--version` option. See https://github.com/pantsbuild/pants/blob/release_2.21.0rc0/src/python/pants/backend/openapi/subsystems/openapi_generator.default.lockfile.txt for the default lockfile contents.
 
 To use a custom lockfile, set this option to a file path relative to the build root, then run `pants jvm-generate-lockfiles --resolve=openapi-generator`.
 

diff --git a/versioned_docs/version-2.21/reference/subsystems/protobuf-java-grpc.mdx b/versioned_docs/version-2.21/reference/subsystems/protobuf-java-grpc.mdx
@@ -73,7 +73,7 @@ lockfile = <str>`}
 
 Path to a lockfile used for installing the tool.
 
-Set to the string `<default>` to use a lockfile provided by Pants, so long as you have not changed the `--version` option. See https://github.com/pantsbuild/pants/blob/release_2.21.0a1/src/python/pants/backend/codegen/protobuf/java/grpc-java.default.lockfile.txt for the default lockfile contents.
+Set to the string `<default>` to use a lockfile provided by Pants, so long as you have not changed the `--version` option. See https://github.com/pantsbuild/pants/blob/release_2.21.0rc0/src/python/pants/backend/codegen/protobuf/java/grpc-java.default.lockfile.txt for the default lockfile contents.
 
 To use a custom lockfile, set this option to a file path relative to the build root, then run `pants jvm-generate-lockfiles --resolve=protobuf-java-grpc`.
 

diff --git a/versioned_docs/version-2.21/reference/subsystems/scalafix.mdx b/versioned_docs/version-2.21/reference/subsystems/scalafix.mdx
@@ -99,7 +99,7 @@ lockfile = <str>`}
 
 Path to a lockfile used for installing the tool.
 
-Set to the string `<default>` to use a lockfile provided by Pants, so long as you have not changed the `--version` option. See https://github.com/pantsbuild/pants/blob/release_2.21.0a1/src/python/pants/backend/scala/lint/scalafix/scalafix.default.lockfile.txt for the default lockfile contents.
+Set to the string `<default>` to use a lockfile provided by Pants, so long as you have not changed the `--version` option. See https://github.com/pantsbuild/pants/blob/release_2.21.0rc0/src/python/pants/backend/scala/lint/scalafix/scalafix.default.lockfile.txt for the default lockfile contents.
 
 To use a custom lockfile, set this option to a file path relative to the build root, then run `pants jvm-generate-lockfiles --resolve=scalafix`.
 

diff --git a/versioned_docs/version-2.21/reference/subsystems/scalafmt.mdx b/versioned_docs/version-2.21/reference/subsystems/scalafmt.mdx
@@ -99,7 +99,7 @@ lockfile = <str>`}
 
 Path to a lockfile used for installing the tool.
 
-Set to the string `<default>` to use a lockfile provided by Pants, so long as you have not changed the `--version` option. See https://github.com/pantsbuild/pants/blob/release_2.21.0a1/src/python/pants/backend/scala/lint/scalafmt/scalafmt.default.lockfile.txt for the default lockfile contents.
+Set to the string `<default>` to use a lockfile provided by Pants, so long as you have not changed the `--version` option. See https://github.com/pantsbuild/pants/blob/release_2.21.0rc0/src/python/pants/backend/scala/lint/scalafmt/scalafmt.default.lockfile.txt for the default lockfile contents.
 
 To use a custom lockfile, set this option to a file path relative to the build root, then run `pants jvm-generate-lockfiles --resolve=scalafmt`.
 

diff --git a/versioned_docs/version-2.21/reference/subsystems/scalapb.mdx b/versioned_docs/version-2.21/reference/subsystems/scalapb.mdx
@@ -91,7 +91,7 @@ lockfile = <str>`}
 
 Path to a lockfile used for installing the tool.
 
-Set to the string `<default>` to use a lockfile provided by Pants, so long as you have not changed the `--version` option. See https://github.com/pantsbuild/pants/blob/release_2.21.0a1/src/python/pants/backend/codegen/protobuf/scala/scalapbc.default.lockfile.txt for the default lockfile contents.
+Set to the string `<default>` to use a lockfile provided by Pants, so long as you have not changed the `--version` option. See https://github.com/pantsbuild/pants/blob/release_2.21.0rc0/src/python/pants/backend/codegen/protobuf/scala/scalapbc.default.lockfile.txt for the default lockfile contents.
 
 To use a custom lockfile, set this option to a file path relative to the build root, then run `pants jvm-generate-lockfiles --resolve=scalapb`.
 

diff --git a/versioned_docs/version-2.21/reference/subsystems/scalatest.mdx b/versioned_docs/version-2.21/reference/subsystems/scalatest.mdx
@@ -105,7 +105,7 @@ lockfile = <str>`}
 
 Path to a lockfile used for installing the tool.
 
-Set to the string `<default>` to use a lockfile provided by Pants, so long as you have not changed the `--version` option. See https://github.com/pantsbuild/pants/blob/release_2.21.0a1/src/python/pants/backend/scala/subsystems/scalatest.default.lockfile.txt for the default lockfile contents.
+Set to the string `<default>` to use a lockfile provided by Pants, so long as you have not changed the `--version` option. See https://github.com/pantsbuild/pants/blob/release_2.21.0rc0/src/python/pants/backend/scala/subsystems/scalatest.default.lockfile.txt for the default lockfile contents.
 
 To use a custom lockfile, set this option to a file path relative to the build root, then run `pants jvm-generate-lockfiles --resolve=scalatest`.
 

diff --git a/versioned_docs/version-2.21/reference/subsystems/scrooge.mdx b/versioned_docs/version-2.21/reference/subsystems/scrooge.mdx
@@ -73,7 +73,7 @@ lockfile = <str>`}
 
 Path to a lockfile used for installing the tool.
 
-Set to the string `<default>` to use a lockfile provided by Pants, so long as you have not changed the `--version` option. See https://github.com/pantsbuild/pants/blob/release_2.21.0a1/src/python/pants/backend/codegen/thrift/scrooge/scrooge.default.lockfile.txt for the default lockfile contents.
+Set to the string `<default>` to use a lockfile provided by Pants, so long as you have not changed the `--version` option. See https://github.com/pantsbuild/pants/blob/release_2.21.0rc0/src/python/pants/backend/codegen/thrift/scrooge/scrooge.default.lockfile.txt for the default lockfile contents.
 
 To use a custom lockfile, set this option to a file path relative to the build root, then run `pants jvm-generate-lockfiles --resolve=scrooge`.
 

diff --git a/versioned_docs/version-2.21/reference/targets/jvm_artifact.mdx b/versioned_docs/version-2.21/reference/targets/jvm_artifact.mdx
@@ -148,7 +148,7 @@ The JVM packages this artifact provides for the purposes of dependency inference
 
 For example, the JVM artifact `junit:junit` might provide `["org.junit.**"]`.
 
-Usually you can leave this field off. If unspecified, Pants will fall back to the `[java-infer].third_party_import_mapping`, then to a built in mapping (https://github.com/pantsbuild/pants/blob/release_2.21.0a1/src/python/pants/jvm/dependency_inference/jvm_artifact_mappings.py), and then finally it will default to the normalized `group` of the artifact. For example, in the absence of any other mapping the artifact `io.confluent:common-config` would default to providing `["io.confluent.**"]`.
+Usually you can leave this field off. If unspecified, Pants will fall back to the `[java-infer].third_party_import_mapping`, then to a built in mapping (https://github.com/pantsbuild/pants/blob/release_2.21.0rc0/src/python/pants/jvm/dependency_inference/jvm_artifact_mappings.py), and then finally it will default to the normalized `group` of the artifact. For example, in the absence of any other mapping the artifact `io.confluent:common-config` would default to providing `["io.confluent.**"]`.
 
 The package path may be made recursive to match symbols in subpackages by adding `.**` to the end of the package path. For example, specify `["org.junit.**"]` to infer a dependency on the artifact for any file importing a symbol from `org.junit` or its subpackages.
 

diff --git a/versioned_docs/version-2.21/reference/targets/pants_requirements.mdx b/versioned_docs/version-2.21/reference/targets/pants_requirements.mdx
@@ -79,7 +79,7 @@ If true, include `pantsbuild.pants.testutil` to write tests for your plugin.
 
 <Field
     type_repr={`str | None`}
-    default_repr={`'== 2.21.0a1'`}
+    default_repr={`'== 2.21.0rc0'`}
 >
 
 The PEP 440 version specifier version of Pants to target. E.g. `== 2.15.*`, or `>= 2.16.0, < 2.17.0`

diff --git a/versioned_docs/version-2.21/reference/targets/python_requirement.mdx b/versioned_docs/version-2.21/reference/targets/python_requirement.mdx
@@ -96,7 +96,7 @@ The modules this requirement provides (used for dependency inference).
 
 For example, the requirement `setuptools` provides `["setuptools", "pkg_resources", "easy_install"]`.
 
-Usually you can leave this field off. If unspecified, Pants will first look at the default module mapping (https://github.com/pantsbuild/pants/blob/release_2.21.0a1/src/python/pants/backend/python/dependency_inference/default_module_mapping.py), and then will default to the normalized project name. For example, the requirement `Django` would default to the module `django`.
+Usually you can leave this field off. If unspecified, Pants will first look at the default module mapping (https://github.com/pantsbuild/pants/blob/release_2.21.0rc0/src/python/pants/backend/python/dependency_inference/default_module_mapping.py), and then will default to the normalized project name. For example, the requirement `Django` would default to the module `django`.
 
 Mutually exclusive with the `type_stub_modules` field.
 
@@ -141,7 +141,7 @@ The modules this requirement provides if the requirement is a type stub (used fo
 
 For example, the requirement `types-requests` provides `["requests"]`.
 
-Usually you can leave this field off. If unspecified, Pants will first look at the default module mapping (https://github.com/pantsbuild/pants/blob/release_2.21.0a1/src/python/pants/backend/python/dependency_inference/default_module_mapping.py). If not found _and_ the requirement name starts with `types-` or `stubs-`, or ends with `-types` or `-stubs`, will default to that requirement name without the prefix/suffix. For example, `types-requests` would default to `requests`. Otherwise, will be treated like a normal requirement (see the `modules` field).
+Usually you can leave this field off. If unspecified, Pants will first look at the default module mapping (https://github.com/pantsbuild/pants/blob/release_2.21.0rc0/src/python/pants/backend/python/dependency_inference/default_module_mapping.py). If not found _and_ the requirement name starts with `types-` or `stubs-`, or ends with `-types` or `-stubs`, will default to that requirement name without the prefix/suffix. For example, `types-requests` would default to `requests`. Otherwise, will be treated like a normal requirement (see the `modules` field).
 
 Mutually exclusive with the `modules` field.
 

diff --git a/versioned_docs/version-2.21/reference/targets/scala_artifact.mdx b/versioned_docs/version-2.21/reference/targets/scala_artifact.mdx
@@ -151,7 +151,7 @@ The JVM packages this artifact provides for the purposes of dependency inference
 
 For example, the JVM artifact `junit:junit` might provide `["org.junit.**"]`.
 
-Usually you can leave this field off. If unspecified, Pants will fall back to the `[java-infer].third_party_import_mapping`, then to a built in mapping (https://github.com/pantsbuild/pants/blob/release_2.21.0a1/src/python/pants/jvm/dependency_inference/jvm_artifact_mappings.py), and then finally it will default to the normalized `group` of the artifact. For example, in the absence of any other mapping the artifact `io.confluent:common-config` would default to providing `["io.confluent.**"]`.
+Usually you can leave this field off. If unspecified, Pants will fall back to the `[java-infer].third_party_import_mapping`, then to a built in mapping (https://github.com/pantsbuild/pants/blob/release_2.21.0rc0/src/python/pants/jvm/dependency_inference/jvm_artifact_mappings.py), and then finally it will default to the normalized `group` of the artifact. For example, in the absence of any other mapping the artifact `io.confluent:common-config` would default to providing `["io.confluent.**"]`.
 
 The package path may be made recursive to match symbols in subpackages by adding `.**` to the end of the package path. For example, specify `["org.junit.**"]` to infer a dependency on the artifact for any file importing a symbol from `org.junit` or its subpackages.