Update docs site for version 2.20.0rc0 (#165)

Docs from https://github.com/pantsbuild/pants/releases/tag/release_2.20.0rc0 --------- Co-authored-by: Huon Wilson <[email protected]>
pantsbuild · Feb 29, 2024 · 6d3c2f6 · 6d3c2f6
1 parent ab27bcd
commit 6d3c2f6
Show file tree

Hide file tree

Showing 166 changed files with 1,426 additions and 1,185 deletions.
diff --git a/old_site_redirects.js b/old_site_redirects.js
@@ -19807,9 +19807,9 @@ export default [
   },
   {
     from: "/v2.20/docs/jvm-overview",
-    to: "/2.20/docs/java-and-scala",
+    to: "/2.20/docs/jvm/java-and-scala",
   },
-  { from: "/v2.20/docs/kotlin", to: "/2.20/docs/java-and-scala/kotlin" },
+  { from: "/v2.20/docs/kotlin", to: "/2.20/docs/jvm/kotlin" },
   {
     from: "/v2.20/docs/shell-overview",
     to: "/2.20/docs/shell",

diff --git a/versioned_docs/version-2.20/docs/introduction/welcome-to-pants.mdx b/versioned_docs/version-2.20/docs/introduction/welcome-to-pants.mdx
@@ -38,7 +38,7 @@ Pants is designed for fast, consistent, ergonomic builds. Some noteworthy featur
 
 ## Which languages and frameworks does Pants support?
 
-- Pants [ships](page:language-support) with support for [Python](../python/overview/index.mdx), [Go](../go/index.mdx), [Java](../java-and-scala/index.mdx), [Scala](../java-and-scala/index.mdx) and [Shell](../shell/index.mdx).
+- Pants [ships](page:language-support) with support for [Python](../python/overview/index.mdx), [Go](../go/index.mdx), [Java](../jvm/java-and-scala.mdx), [Scala](../jvm/java-and-scala.mdx), [Kotlin](../jvm/kotlin.mdx), and [Shell](../shell/index.mdx).
 - Pants supports a wide range of code generators (such as Thrift, Protobuf, Scrooge and Avro), linters and formatters, and it is easy to add support for new or custom ones
 - Pants can create standalone binaries, [Docker images](../docker/index.mdx), AWS Lambdas and GCP Cloud Functions
 

diff --git a/versioned_docs/version-2.20/docs/java-and-scala/_category_.json b/versioned_docs/version-2.20/docs/java-and-scala/_category_.json
diff --git a/versioned_docs/version-2.20/docs/jvm/_category_.json b/versioned_docs/version-2.20/docs/jvm/_category_.json
@@ -0,0 +1,4 @@
+{
+  "label": "JVM",
+  "position": 7
+}
diff --git a/...ersion-2.20/docs/java-and-scala/index.mdx → .../version-2.20/docs/jvm/java-and-scala.mdx b/...ersion-2.20/docs/java-and-scala/index.mdx → .../version-2.20/docs/jvm/java-and-scala.mdx
@@ -1,5 +1,5 @@
 ---
-    title: Java and Scala overview
+    title: Java and Scala
     sidebar_position: 0
 ---
 

diff --git a/...rsion-2.20/docs/java-and-scala/kotlin.mdx → ...ned_docs/version-2.20/docs/jvm/kotlin.mdx b/...rsion-2.20/docs/java-and-scala/kotlin.mdx → ...ned_docs/version-2.20/docs/jvm/kotlin.mdx
diff --git a/versioned_docs/version-2.20/docs/python/overview/lockfiles.mdx b/versioned_docs/version-2.20/docs/python/overview/lockfiles.mdx
@@ -184,6 +184,9 @@ It is strongly recommended that these tools be installed from a hermetic lockfil
 
 The only time you need to think about this is if you want to customize the tool requirements that Pants uses. This might be the case if you want to modify the version of a tool or add extra requirements (for example, tool plugins).
 
+:::caution Exporting tools requires a custom lockfile
+:::
+
 If you want a tool to be installed from some resolve, instead of from the built-in lockfile, you set `install_from_resolve` and `requirements` on the tool's config section:
 
 ```toml title="pants.toml"

diff --git a/versioned_docs/version-2.20/docs/python/overview/pex.mdx b/versioned_docs/version-2.20/docs/python/overview/pex.mdx
@@ -87,7 +87,8 @@ In these cases you can override the default shebang using the [`shebang`](../../
 
 Pants makes use of the [Pex](https://github.com/pex-tool/pex) command-line tool internally for building PEXes. The Pex version that Pants uses is specified by the `version` option under the `pex-cli` subsystem. The known Pex versions are specified by the `known_versions` option under the `pex-cli` subsystem. You can see all Pex tool options and their current values by running `pants help-advanced pex-cli`. To upgrade the Pex version, update these option values accordingly. For instance, in `pants.toml`, to upgrade to Pex 2.1.143:
 
-```[pex-cli]
+```
+[pex-cli]
 version = "v2.1.143"
 known_versions = [
   "v2.1.143|macos_arm64|7dba8776000b4f75bc9af850cb65b2dc7720ea211733e8cb5243c0b210ef3c19|4194291",
@@ -101,6 +102,7 @@ The Pex version determines which Pip versions are supported. To see the lists of
 
 The Pip version that Pex uses is determined by the `pip_version` option in Pants. To upgrade the Pip version, update this option value accordingly. For instance, in `pants.toml`, to set the Pip version to be the latest supported by Pex:
 
-```[python]
+```
+[python]
 pip_version = "latest"
 ```
diff --git a/versioned_docs/version-2.20/docs/using-pants/key-concepts/backends.mdx b/versioned_docs/version-2.20/docs/using-pants/key-concepts/backends.mdx
@@ -82,14 +82,14 @@ The list of all backends (both stable and experimental) is also available via `p
 | `pants.backend.experimental.go.lint.vet`                           | Enables support for running `go vet`                                                                                                                  | [Go overview](../../go/index.mdx)                                                                     |
 | `pants.backend.experimental.helm`                                  | Enables core Helm support: [https://helm.sh](https://helm.sh)                                                                                         | [Helm overview](../../helm/index.mdx)                                                                 |
 | `pants.backend.experimental.helm.check.kubeconfirm`                | Enables Kubeconform, a fast Kubernetes manifest validator: [https://github.com/yannh/kubeconform](https://github.com/yannh/kubeconform)               | [Helm overview](../../helm/index.mdx)                                                                 |
-| `pants.backend.experimental.java`                                  | Enables core Java support.                                                                                                                            | [Java & Scala overview](../../java-and-scala/index.mdx)                                               |
-| `pants.backend.experimental.java.debug_goals`                      | Enable additional goals for introspecting Java targets                                                                                                | [Java & Scala overview](../../java-and-scala/index.mdx)                                               |
-| `pants.backend.experimental.java.lint.google_java_format`          | Enables Google Java Format.                                                                                                                           | [Java & Scala overview](../../java-and-scala/index.mdx)                                               |
+| `pants.backend.experimental.java`                                  | Enables core Java support.                                                                                                                            | [Java & Scala overview](../../jvm/java-and-scala.mdx)                                               |
+| `pants.backend.experimental.java.debug_goals`                      | Enable additional goals for introspecting Java targets                                                                                                | [Java & Scala overview](../../jvm/java-and-scala.mdx)                                               |
+| `pants.backend.experimental.java.lint.google_java_format`          | Enables Google Java Format.                                                                                                                           | [Java & Scala overview](../../jvm/java-and-scala.mdx)                                               |
 | `pants.backend.experimental.javascript`                            | Enables core JavaScript support.                                                                                                                      |                                                                                                       |
 | `pants.backend.experimental.javascript.lint.prettier`              | Enables Prettier, a JavaScript (and more) autoformatter: [https://prettier.io](https://prettier.io)                                                   |                                                                                                       |
-| `pants.backend.experimental.kotlin`                                | Enables core Kotlin support                                                                                                                           | [Kotlin](../../java-and-scala/kotlin.mdx)                                                             |
-| `pants.backend.experimental.kotlin.debug_goals`                    | Enables additional goals for introspecting Kotlin targets                                                                                             | [Kotlin](../../java-and-scala/kotlin.mdx)                                                             |
-| `pants.backend.experimental.kotlin.lint.ktlint`                    | Enables ktlint, an anti-bikeshedding linter with built-in formatter: [https://pinterest.github.io/ktlint/](https://pinterest.github.io/ktlint/)       | [Kotlin](../../java-and-scala/kotlin.mdx)                                                             |
+| `pants.backend.experimental.kotlin`                                | Enables core Kotlin support                                                                                                                           | [Kotlin](../../jvm/kotlin.mdx)                                                             |
+| `pants.backend.experimental.kotlin.debug_goals`                    | Enables additional goals for introspecting Kotlin targets                                                                                             | [Kotlin](../../jvm/kotlin.mdx)                                                             |
+| `pants.backend.experimental.kotlin.lint.ktlint`                    | Enables ktlint, an anti-bikeshedding linter with built-in formatter: [https://pinterest.github.io/ktlint/](https://pinterest.github.io/ktlint/)       | [Kotlin](../../jvm/kotlin.mdx)                                                             |
 | `pants.backend.experimental.openapi`                               | Enables core OpenAPI support: [https://swagger.io/specification/](https://swagger.io/specification/)                                                  | [`openapi`](../../../reference/subsystems/openapi.mdx)                                                |
 | `pants.backend.experimental.openapi.codegen.java`                  | Enables generating Java from OpenAPI                                                                                                                  |                                                                                                       |
 | `pants.backend.experimental.openapi.lint.openapi_format`           | Enables openapi-format: [https://github.com/thim81/openapi-format](https://github.com/thim81/openapi-format)                                          |                                                                                                       |
@@ -104,9 +104,9 @@ The list of all backends (both stable and experimental) is also available via `p
 | `pants.backend.experimental.python.typecheck.pyright`              | Enables Pyright, a Python type checker: [https://github.com/microsoft/pyright](https://github.com/microsoft/pyright)                                  |                                                                                                       |
 | `pants.backend.experimental.python.typecheck.pytype`               | Enables Pytype, a Python type checker: [https://google.github.io/pytype/](https://google.github.io/pytype/)                                           |                                                                                                       |
 | `pants.backend.experimental.rust`                                  | Enables core Rust support.                                                                                                                            |                                                                                                       |
-| `pants.backend.experimental.scala`                                 | Enables core Scala support.                                                                                                                           | [Java & Scala overview](../../java-and-scala/index.mdx)                                               |
-| `pants.backend.experimental.scala.debug_goals`                     | Enables additional goals for introspecting Scala targets                                                                                              | [Java & Scala overview](../../java-and-scala/index.mdx)                                               |
-| `pants.backend.experimental.scala.lint.scalafmt`                   | Enables the Scalafmt formatter.                                                                                                                       | [Java & Scala overview](../../java-and-scala/index.mdx)                                               |
+| `pants.backend.experimental.scala`                                 | Enables core Scala support.                                                                                                                           | [Java & Scala overview](../../jvm/java-and-scala.mdx)                                               |
+| `pants.backend.experimental.scala.debug_goals`                     | Enables additional goals for introspecting Scala targets                                                                                              | [Java & Scala overview](../../jvm/java-and-scala.mdx)                                               |
+| `pants.backend.experimental.scala.lint.scalafmt`                   | Enables the Scalafmt formatter.                                                                                                                       | [Java & Scala overview](../../jvm/java-and-scala.mdx)                                               |
 | `pants.backend.experimental.swift`                                 | Enables core Swift support.                                                                                                                           |                                                                                                       |
 | `pants.backend.experimental.terraform`                             | Enables core Terraform support.                                                                                                                       |                                                                                                       |
 | `pants.backend.experimental.terraform.lint.tfsec`                  | Enables tfsec, for static analysis of Terraform: [https://aquasecurity.github.io/tfsec/](https://aquasecurity.github.io/tfsec/)                       |                                                                                                       |

diff --git a/versioned_docs/version-2.20/docs/using-pants/key-concepts/options.mdx b/versioned_docs/version-2.20/docs/using-pants/key-concepts/options.mdx
@@ -105,9 +105,8 @@ repo_host = "repo.%(domain)s"
 indexes.add = ["https://%(env.PY_REPO)s@%(repo_host)s/index"]
 ```
 
-Learn more about exporting environment variables in the
-[`.pants.bootstrap`](../using-pants/key-concepts/options.mdx#pantsbootstrap-file)) Bash script that is sourced
-before Pants runs.
+Learn more about exporting environment variables in the [`.pants.bootstrap`](#pantsbootstrap-file))
+Bash script that is sourced before Pants runs.
 
 ## Option types
 

diff --git a/versioned_docs/version-2.20/docs/using-pants/project-introspection.mdx b/versioned_docs/version-2.20/docs/using-pants/project-introspection.mdx
@@ -127,6 +127,72 @@ To include the original target itself, use `--closed`:
 helloworld/main.py:lib
 ```
 
+## Export dependency graph
+
+Both `dependencies` and `dependents` goals have the `--format` option allowing you to export data in multiple formats.
+Exporting information about the dependencies and dependents in JSON format will produce the
+[adjacency list](https://en.wikipedia.org/wiki/Adjacency_list) of your dependency graph:
+
+```bash
+$ pants dependencies --format=json \
+  helloworld/greet/greeting.py \
+  helloworld/translator/translator_test.py
+
+{
+    "helloworld/greet/greeting.py:lib": [
+        "//:reqs#setuptools",
+        "//:reqs#types-setuptools",
+        "helloworld/greet:translations",
+        "helloworld/translator/translator.py:lib"
+    ],
+    "helloworld/translator/translator_test.py:tests": [
+        "//:reqs#pytest",
+        "helloworld/translator/translator.py:lib"
+    ]
+}
+```
+
+This has various applications, and you could analyze, visualize, and process the data further. Sometimes, a fairly
+straightforward `jq` query would suffice, but for anything more complex, it may make sense to write a small program
+to process the exported graph. For instance, you could:
+
+* find tests with most transitive dependencies
+
+```bash
+$ pants dependencies --filter-target-type=python_test --format=json :: \
+  | jq -r 'to_entries[] | "\(.key)\t\(.value | length)"' \
+  | sort -k2 -n
+```
+
+* find resources that only a few other targets depend on
+
+```bash
+$ pants dependents --filter-target-type=resource --format=json :: \
+  | jq -r 'to_entries[] | select(.value | length < 2)'
+```
+
+* find files within the `src/` directory that transitively lead to the most tests
+
+```python
+# depgraph.py
+import json
+
+with open("data.json") as fh:
+    data = json.load(fh)
+
+for source, dependents in data.items():
+    print(source, len([d for d in dependents if d.startswith("tests/")]))
+```
+
+```bash
+$ pants dependents --transitive --format=json src:: > data.json
+$ python3 depgraph.py | sort -k2 -n
+```
+
+For more sophisticated graph querying, you may want to look into graph libraries such as [`networkx`](https://networkx.org/).
+In a larger repository, it may make sense to track the health of the dependency graph and use the output
+of the graph export to identify parts of your codebase that would benefit from refactoring.
+
 ## `filedeps` - find which files a target owns
 
 `filedeps` outputs all of the files belonging to a target, based on its `sources` field.

diff --git a/versioned_docs/version-2.20/docs/using-pants/setting-up-an-ide.mdx b/versioned_docs/version-2.20/docs/using-pants/setting-up-an-ide.mdx
@@ -49,7 +49,7 @@ The `--py-resolve-format=symlinked_immutable_virtualenv` option symlinks to an i
 
 ### Tool virtualenvs
 
-`pants export` can also create a virtualenv for each of the Python tools you use via Pants, such as `black`, `isort`, `pytest`, `mypy`, `flake8` and so on (you can run `/pants help tools` to get a list of the tools Pants uses). Use the tool name as the resolve name argument to the `--resolve` flag. This allows you to configure your editor to use the same version of the tool as Pants does for workflows like formatting on save.
+`pants export` can also create a virtualenv for each of the Python tools you use via Pants, such as `black`, `isort`, `pytest`, `mypy`, `flake8` and so on. This allows you to configure your editor to use the same version of the tool as Pants does for workflows like formatting on save. Follow [the instructions for creating a tool lockfile](../../python/overview/lockfiles#lockfiles-for-tools).
 
 ## Generated code
 

diff --git a/versioned_docs/version-2.20/docs/using-pants/troubleshooting-common-issues.mdx b/versioned_docs/version-2.20/docs/using-pants/troubleshooting-common-issues.mdx
@@ -108,13 +108,13 @@ Is the missing import from first-party code? Common issues:
 Common issues with both first and third-party imports:
 
 - Ambiguity. >1 target exposes the same module/package.
-  - If it's a third-party dependency, you should likely use multiple "resolves" (lockfiles). Each resolve should have no more than one of the same requirement. See [Python](../python/overview/lockfiles.mdx#multiple-lockfiles) and [JVM](../java-and-scala/index.mdx).
+  - If it's a third-party dependency, you should likely use multiple "resolves" (lockfiles). Each resolve should have no more than one of the same requirement. See [Python](../python/overview/lockfiles.mdx#multiple-lockfiles) and [JVM](../jvm/java-and-scala.mdx).
   - If it's a first-party dependency, you may have unintentionally created multiple targets owning the same file. Run `pants list path/to/file.ext` to see all owners. This often happens from overlapping `sources` fields. If this was intentional, follow the instructions in the ambiguity warning to disambiguate via the `dependencies` field.
 - Some target types like `resources` and `files` often need to be explicitly added to the `dependencies` field and cannot be inferred (yet).
 - Multiple resolves (Python and JVM).
   - A target can only depend on targets that share the same "resolve" (lockfile).
   - Pants will warn when it detects that the import exists in another resolve. This usually implies you should either change the current target's `resolve` field, or use the `parametrize()` mechanism so that the code works with multiple resolves.
-  - See [Python](../python/overview/lockfiles.mdx#multiple-lockfiles) and [JVM](../java-and-scala/index.mdx).
+  - See [Python](../python/overview/lockfiles.mdx#multiple-lockfiles) and [JVM](../jvm/java-and-scala.mdx).
 
 When debugging dependency inference, it can help to explicitly add the problematic dependency to the `dependencies` field to see if it gets the code running. If so, you can then try to figure out why dependency inference is not working.