Update doc_url calls for new website (Cherry-pick of #20583) (#20588)

This PR fixes #20427 by updating our use of `doc_url` to reflect the new
website structure. It does this semi-automatically, spread across
separate commits:

1. Update the `doc_url` function to reflect the new website structure,
including support for unversioned URLs like
https://www.pantsbuild.org/community/getting-help
2. Apply automated rewrites (see below for details)
3. Do one or two manual fix-ups

The automatic rewrites were done by:

1. finding the args passed to `doc_url`: `rg --only-matching
"doc_url\([^)]*\)" . | cut -f2 -d\( | cut -f1 -d\) | tr \' \" | sort -u`
2. put them into CSV file, then use
https://github.com/pantsbuild/pantsbuild.org/blob/92d5ce8d3442890c3fbeb0fade620b762ae2aa7e/old_site_redirects.js
to find the new URL for each one
3. transform the CSV into a long series of `s@...@...@` substitutions
for `sed`
4. apply them with `git ls-files '*.py' '*.rs' | xargs sed -i '' "..."`
5. do a basic check that the appropriate files that call `doc_url` were
updated: identify non-updated files via `comm -13 <(git diff --name-only
be42bc0^...be42bc0) <( rg --files-with-matches doc_url | sort)`.
The files without updates are expected, e.g.
- `src/python/pants/util/docutil.py` that defines `doc_url` itself (and
the test file etc.)
- `src/python/pants/backend/codegen/avro/target_types.py` that didn't
have an immediately obvious replacement, with more examples in #20584

This is marked for cherry-picking to 2.20.x. There _are_ redirects for
the URLs for 2.20, but it seems a bit annoying to rely on them, if we
don't have to.

<details>

```csv
old,new
"getting-help","community/getting-help"
"advanced-target-selection","docs/using-pants/advanced-target-selection"
"anonymous-telemetry","docs/using-pants/anonymous-telemetry"
"awslambda-python","docs/python/integrations/aws-lambda"
"enabling-backends","docs/using-pants/key-concepts/backends"
"google-cloud-function-python","docs/python/integrations/google-cloud-functions"
"installation","docs/getting-started/installing-pants"
"macros","docs/writing-plugins/macros"
"options","docs/using-pants/key-concepts/options"
"options#addremove-semantics","docs/using-pants/key-concepts/options#addremove-semantics"
"options#config-file-entries","docs/using-pants/key-concepts/options#config-file-entries"
"options#config-file-interpolation","docs/using-pants/key-concepts/options#config-file-interpolation"
"options#pantsrc-file","docs/using-pants/key-concepts/options#pantsrc-file"
"options#reading-individual-option-values-from-files","docs/using-pants/key-concepts/options#reading-individual-option-values-from-files"
"pex","docs/python/overview/pex"
"plugin-upgrade-guide","docs/writing-plugins/common-plugin-tasks/plugin-upgrade-guide"
"plugins-overview","docs/writing-plugins/overview"
"plugins-setup-py","docs/writing-plugins/common-plugin-tasks/custom-python-artifact-kwargs"
"protobuf-go","docs/go/integrations/protobuf"
"protobuf-python","docs/python/integrations/protobuf-and-grpc"
"python-check-goal","docs/python/goals/check"
"python-distributions","docs/python/overview/building-distributions"
"python-interpreter-compatibility","docs/python/overview/interpreter-compatibility"
"python-lockfiles#lockfiles-for-tools","docs/python/overview/lockfiles#lockfiles-for-tools"
"python-test-goal","docs/python/goals/test"
"python-test-goal#pytest-version-and-plugins","docs/python/goals/test#pytest-version-and-plugins"
"python-third-party-dependencies","docs/python/overview/third-party-dependencies"
"python-third-party-dependencies#local-requirements","docs/python/overview/third-party-dependencies#local-requirements"
"python-third-party-dependencies#multiple-lockfiles","docs/python/overview/lockfiles#multiple-lockfiles"
"python-third-party-dependencies#user-lockfiles","docs/python/overview/third-party-dependencies#user-lockfiles"
"reference-deploy_jar#coderesolvecode","reference/targets/deploy_jar#resolve"
"reference-global#remote_oauth_bearer_token","reference/global-options#remote_oauth_bearer_token"
"remote-caching-execution","docs/using-pants/remote-caching-and-execution"
"source-roots","docs/using-pants/key-concepts/source-roots"
"tagging-docker-images","docs/docker/tagging-docker-images"
"target-api-concepts","docs/writing-plugins/the-target-api/concepts"
"targets","docs/using-pants/key-concepts/targets-and-build-files"
"targets#field-default-values","docs/using-pants/key-concepts/targets-and-build-files#field-default-values"
"targets#dependencies-and-dependency-inference","docs/using-pants/key-concepts/targets-and-build-files#dependencies-and-dependency-inference"
"thrift-python","docs/python/integrations/thrift"
"troubleshooting","docs/using-pants/troubleshooting-common-issues"
"troubleshooting#import-errors-and-missing-dependencies","docs/using-pants/troubleshooting-common-issues#import-errors-and-missing-dependencies"
"upgrade-tips","docs/releases/upgrade-tips"
```

```python
import pandas as pd
print("\n".join(
  f"""s@\\(doc_url.*[\\"']\\){r.old}\\([\\"']\\)@\\1{r.new}\\2@g;"""
  for _, r in pd.read_csv("replacements.csv").iterrows()
))
```

```shell
git ls-files '*.py' '*.rs' | xargs sed -i '' "
s@\(doc_url.*[\"']\)getting-help\([\"']\)@\1community/getting-help\2@g;
s@\(doc_url.*[\"']\)advanced-target-selection\([\"']\)@\1docs/using-pants/advanced-target-selection\2@g;
s@\(doc_url.*[\"']\)anonymous-telemetry\([\"']\)@\1docs/using-pants/anonymous-telemetry\2@g;
s@\(doc_url.*[\"']\)awslambda-python\([\"']\)@\1docs/python/integrations/aws-lambda\2@g;
s@\(doc_url.*[\"']\)enabling-backends\([\"']\)@\1docs/using-pants/key-concepts/backends\2@g;
s@\(doc_url.*[\"']\)google-cloud-function-python\([\"']\)@\1docs/python/integrations/google-cloud-functions\2@g;
s@\(doc_url.*[\"']\)installation\([\"']\)@\1docs/getting-started/installing-pants\2@g;
s@\(doc_url.*[\"']\)macros\([\"']\)@\1docs/writing-plugins/macros\2@g;
s@\(doc_url.*[\"']\)options\([\"']\)@\1docs/using-pants/key-concepts/options\2@g;
s@\(doc_url.*[\"']\)options#addremove-semantics\([\"']\)@\1docs/using-pants/key-concepts/options#addremove-semantics\2@g;
s@\(doc_url.*[\"']\)options#config-file-entries\([\"']\)@\1docs/using-pants/key-concepts/options#config-file-entries\2@g;
s@\(doc_url.*[\"']\)options#config-file-interpolation\([\"']\)@\1docs/using-pants/key-concepts/options#config-file-interpolation\2@g;
s@\(doc_url.*[\"']\)options#pantsrc-file\([\"']\)@\1docs/using-pants/key-concepts/options#pantsrc-file\2@g;
s@\(doc_url.*[\"']\)options#reading-individual-option-values-from-files\([\"']\)@\1docs/using-pants/key-concepts/options#reading-individual-option-values-from-files\2@g;
s@\(doc_url.*[\"']\)pex\([\"']\)@\1docs/python/overview/pex\2@g;
s@\(doc_url.*[\"']\)plugin-upgrade-guide\([\"']\)@\1docs/writing-plugins/common-plugin-tasks/plugin-upgrade-guide\2@g;
s@\(doc_url.*[\"']\)plugins-overview\([\"']\)@\1docs/writing-plugins/overview\2@g;
s@\(doc_url.*[\"']\)plugins-setup-py\([\"']\)@\1docs/writing-plugins/common-plugin-tasks/custom-python-artifact-kwargs\2@g;
s@\(doc_url.*[\"']\)protobuf-go\([\"']\)@\1docs/go/integrations/protobuf\2@g;
s@\(doc_url.*[\"']\)protobuf-python\([\"']\)@\1docs/python/integrations/protobuf-and-grpc\2@g;
s@\(doc_url.*[\"']\)python-check-goal\([\"']\)@\1docs/python/goals/check\2@g;
s@\(doc_url.*[\"']\)python-distributions\([\"']\)@\1docs/python/overview/building-distributions\2@g;
s@\(doc_url.*[\"']\)python-interpreter-compatibility\([\"']\)@\1docs/python/overview/interpreter-compatibility\2@g;
s@\(doc_url.*[\"']\)python-lockfiles#lockfiles-for-tools\([\"']\)@\1docs/python/overview/lockfiles#lockfiles-for-tools\2@g;
s@\(doc_url.*[\"']\)python-test-goal\([\"']\)@\1docs/python/goals/test\2@g;
s@\(doc_url.*[\"']\)python-test-goal#pytest-version-and-plugins\([\"']\)@\1docs/python/goals/test#pytest-version-and-plugins\2@g;
s@\(doc_url.*[\"']\)python-third-party-dependencies\([\"']\)@\1docs/python/overview/third-party-dependencies\2@g;
s@\(doc_url.*[\"']\)python-third-party-dependencies#local-requirements\([\"']\)@\1docs/python/overview/third-party-dependencies#local-requirements\2@g;
s@\(doc_url.*[\"']\)python-third-party-dependencies#multiple-lockfiles\([\"']\)@\1docs/python/overview/lockfiles#multiple-lockfiles\2@g;
s@\(doc_url.*[\"']\)python-third-party-dependencies#user-lockfiles\([\"']\)@\1docs/python/overview/third-party-dependencies#user-lockfiles\2@g;
s@\(doc_url.*[\"']\)reference-deploy_jar#coderesolvecode\([\"']\)@\1reference/targets/deploy_jar#resolve\2@g;
s@\(doc_url.*[\"']\)reference-global#remote_oauth_bearer_token\([\"']\)@\1reference/global-options#remote_oauth_bearer_token\2@g;
s@\(doc_url.*[\"']\)remote-caching-execution\([\"']\)@\1docs/using-pants/remote-caching-and-execution\2@g;
s@\(doc_url.*[\"']\)source-roots\([\"']\)@\1docs/using-pants/key-concepts/source-roots\2@g;
s@\(doc_url.*[\"']\)tagging-docker-images\([\"']\)@\1docs/docker/tagging-docker-images\2@g;
s@\(doc_url.*[\"']\)target-api-concepts\([\"']\)@\1docs/writing-plugins/the-target-api/concepts\2@g;
s@\(doc_url.*[\"']\)targets\([\"']\)@\1docs/using-pants/key-concepts/targets-and-build-files\2@g;
s@\(doc_url.*[\"']\)targets#field-default-values\([\"']\)@\1docs/using-pants/key-concepts/targets-and-build-files#field-default-values\2@g;
s@\(doc_url.*[\"']\)targets#dependencies-and-dependency-inference\([\"']\)@\1docs/using-pants/key-concepts/targets-and-build-files#dependencies-and-dependency-inference\2@g;
s@\(doc_url.*[\"']\)thrift-python\([\"']\)@\1docs/python/integrations/thrift\2@g;
s@\(doc_url.*[\"']\)troubleshooting\([\"']\)@\1docs/using-pants/troubleshooting-common-issues\2@g;
s@\(doc_url.*[\"']\)troubleshooting#import-errors-and-missing-dependencies\([\"']\)@\1docs/using-pants/troubleshooting-common-issues#import-errors-and-missing-dependencies\2@g;
s@\(doc_url.*[\"']\)upgrade-tips\([\"']\)@\1docs/releases/upgrade-tips\2@g;
"
```

</details>

Co-authored-by: Huon Wilson <[email protected]>

Author: WorkerPants

src/python/pants/backend/awslambda/python/target_types.py

@@ -191,7 +191,7 @@ class PythonAWSLambda(_AWSLambdaBaseTarget):
         f"""
         A self-contained Python function suitable for uploading to AWS Lambda.
 
-        See {doc_url('awslambda-python')}.
+        See {doc_url('docs/python/integrations/aws-lambda')}.
         """
     )
 
@@ -207,7 +207,7 @@ class PythonAWSLambdaLayer(_AWSLambdaBaseTarget):
         f"""
         A Python layer suitable for uploading to AWS Lambda.
 
-        See {doc_url('awslambda-python')}.
+        See {doc_url('docs/python/integrations/aws-lambda')}.
         """
     )
 

src/python/pants/backend/codegen/protobuf/python/python_protobuf_subsystem.py

@@ -35,7 +35,7 @@ class PythonProtobufSubsystem(Subsystem):
         f"""
         Options related to the Protobuf Python backend.
 
-        See {doc_url('protobuf-python')}.
+        See {doc_url('docs/python/integrations/protobuf-and-grpc')}.
         """
     )
 

src/python/pants/backend/codegen/protobuf/target_types.py

@@ -66,8 +66,8 @@ class ProtobufSourceTarget(Target):
         A single Protobuf file used to generate various languages.
 
         See language-specific docs:
-            Python: {doc_url('protobuf-python')}
-            Go: {doc_url('protobuf-go')}
+            Python: {doc_url('docs/python/integrations/protobuf-and-grpc')}
+            Go: {doc_url('docs/go/integrations/protobuf')}
         """
     )
 

src/python/pants/backend/codegen/thrift/target_types.py

@@ -72,7 +72,7 @@ class ThriftSourceTarget(Target):
         A single Thrift file used to generate various languages.
 
         See language-specific docs:
-            Python: {doc_url('thrift-python')}
+            Python: {doc_url('docs/python/integrations/thrift')}
         """
     )
 

src/python/pants/backend/codegen/utils.py

@@ -54,7 +54,7 @@ def find_python_runtime_library_or_raise_error(
                 No `python_requirement` target was found with the module `{runtime_library_module}`
                 in your project{for_resolve_str}, so the Python code generated from the target
                 {codegen_address} will not work properly. See
-                {doc_url('python-third-party-dependencies')} for how to add a requirement, such as
+                {doc_url('docs/python/overview/third-party-dependencies')} for how to add a requirement, such as
                 adding to requirements.txt. Usually you will want to use the
                 `{recommended_requirement_name}` project at {recommended_requirement_url}.
 

src/python/pants/backend/docker/target_types.py

@@ -149,7 +149,7 @@ class DockerImageTagsField(StringSequenceField):
 
         {_interpolation_help.format(kind="tag")}
 
-        See {doc_url('tagging-docker-images')}.
+        See {doc_url('docs/docker/tagging-docker-images')}.
         """
     )
 

src/python/pants/backend/google_cloud_function/python/target_types.py

@@ -125,7 +125,7 @@ class PythonGoogleCloudFunction(Target):
         f"""
         A self-contained Python function suitable for uploading to Google Cloud Function.
 
-        See {doc_url('google-cloud-function-python')}.
+        See {doc_url('docs/python/integrations/google-cloud-functions')}.
         """
     )
 

src/python/pants/backend/python/dependency_inference/rules.py

@@ -346,7 +346,7 @@ async def _handle_unowned_imports(
 
         If you do not expect an import to be inferrable, add `# pants: no-infer-dep` to the
         import line. Otherwise, see
-        {doc_url('troubleshooting#import-errors-and-missing-dependencies')} for common problems.
+        {doc_url('docs/using-pants/troubleshooting-common-issues#import-errors-and-missing-dependencies')} for common problems.
         """
     )
     if unowned_dependency_behavior is UnownedDependencyUsage.LogWarning:

src/python/pants/backend/python/goals/pytest_runner.py

@@ -243,7 +243,7 @@ async def validate_pytest_cov_included(_pytest: PyTest):
                 `{_pytest.install_from_resolve}` used to install pytest is missing
                 `pytest-cov`, which is needed to collect coverage data.
 
-                See {doc_url("python-test-goal#pytest-version-and-plugins")} for details
+                See {doc_url("docs/python/goals/test#pytest-version-and-plugins")} for details
                 on how to set up a custom resolve for use by pytest.
                 """
             )

src/python/pants/backend/python/goals/repl.py

@@ -54,7 +54,7 @@ def maybe_get_resolve(t: Target) -> str | None:
         raise NoCompatibleResolveException.bad_input_roots(
             root_targets,
             maybe_get_resolve=maybe_get_resolve,
-            doc_url_slug="python-third-party-dependencies#multiple-lockfiles",
+            doc_url_slug="docs/python/overview/lockfiles#multiple-lockfiles",
             workaround=softwrap(
                 f"""
                 To work around this, choose which resolve you want to use from above. Then, run

src/python/pants/backend/python/lint/flake8/subsystem.py

@@ -108,7 +108,7 @@ class Flake8(PythonToolBase):
             example, if your plugin is at `build-support/flake8/custom_plugin.py`, add
             `'build-support/flake8'` to `[source].root_patterns` in `pants.toml`. This is
             necessary for Pants to know how to tell Flake8 to discover your plugin. See
-            {doc_url('source-roots')}
+            {doc_url('docs/using-pants/key-concepts/source-roots')}
 
             You must also set `[flake8:local-plugins]` in your Flake8 config file.
 
@@ -123,7 +123,7 @@ class Flake8(PythonToolBase):
             directory or a subdirectory.
 
             To instead load third-party plugins, add them to a custom resolve alongside
-            flake8 itself, as described in {doc_url("python-lockfiles#lockfiles-for-tools")}.
+            flake8 itself, as described in {doc_url("docs/python/overview/lockfiles#lockfiles-for-tools")}.
             """
         ),
     )

src/python/pants/backend/python/lint/pylint/subsystem.py

@@ -106,7 +106,7 @@ class Pylint(PythonToolBase):
             example, if your plugin is at `build-support/pylint/custom_plugin.py`, add
             `'build-support/pylint'` to `[source].root_patterns` in `pants.toml`. This is
             necessary for Pants to know how to tell Pylint to discover your plugin. See
-            {doc_url('source-roots')}
+            {doc_url('docs/using-pants/key-concepts/source-roots')}
 
             You must also set `load-plugins=$module_name` in your Pylint config file.
 
@@ -115,7 +115,7 @@ class Pylint(PythonToolBase):
             directory or a subdirectory.
 
             To instead load third-party plugins, add them to a custom resolve alongside
-            pylint itself, as described in {doc_url("python-lockfiles#lockfiles-for-tools")}.
+            pylint itself, as described in {doc_url("docs/python/overview/lockfiles#lockfiles-for-tools")}.
             """
         ),
     )

src/python/pants/backend/python/packaging/pyoxidizer/rules.py

@@ -133,7 +133,7 @@ async def package_pyoxidizer_binary(
                 The `{PyOxidizerTarget.alias}` target {field_set.address} must include
                 in its `dependencies` field at least one `python_distribution` target that produces a
                 `.whl` file. For example, if using `{GenerateSetupField.alias}=True`, then make sure
-                `{WheelField.alias}=True`. See {doc_url('python-distributions')}.
+                `{WheelField.alias}=True`. See {doc_url('docs/python/overview/building-distributions')}.
                 """
             )
         )

src/python/pants/backend/python/packaging/pyoxidizer/target_types.py

@@ -78,14 +78,14 @@ class PyOxidizerDependenciesField(Dependencies):
 
         The distribution(s) must generate at least one wheel file. For example, if using
         `{GenerateSetupField.alias}=True`, then make sure `{WheelField.alias}=True`. See
-        {doc_url('python-distributions')}.
+        {doc_url('docs/python/overview/building-distributions')}.
 
         Usually, you only need to specify a single `python_distribution`. However, if
         that distribution depends on another first-party distribution in your repository, you
         must specify that dependency too, otherwise PyOxidizer would try installing the
         distribution from PyPI. Note that a `python_distribution` target might depend on
         another `python_distribution` target even if it is not included in its own `dependencies`
-        field, as explained at {doc_url('python-distributions')}; if code from one distribution
+        field, as explained at {doc_url('docs/python/overview/building-distributions')}; if code from one distribution
         imports code from another distribution, then there is a dependency and you must
         include both `python_distribution` targets in the `dependencies` field of this
         `pyoxidizer_binary` target.
@@ -146,7 +146,7 @@ class PyOxidizerTarget(Target):
         A single-file Python executable with a Python interpreter embedded, built via PyOxidizer.
 
         To use this target, first create a `python_distribution` target with the code you want
-        included in your binary, per {doc_url('python-distributions')}. Then add this
+        included in your binary, per {doc_url('docs/python/overview/building-distributions')}. Then add this
         `python_distribution` target to the `dependencies` field. See the `help` for
         `dependencies` for more information.
 

src/python/pants/backend/python/subsystems/python_tool_base.py

@@ -58,7 +58,7 @@ class PythonToolRequirementsBase(Subsystem):
             If specified, install the tool using the lockfile for this named resolve.
 
             This resolve must be defined in `[python].resolves`, as described in
-            {doc_url("python-third-party-dependencies#user-lockfiles")}.
+            {doc_url("docs/python/overview/third-party-dependencies#user-lockfiles")}.
 
             The resolve's entire lockfile will be installed, unless specific requirements are
             listed via the `requirements` option, in which case only those requirements

src/python/pants/backend/python/subsystems/repos.py

@@ -78,19 +78,19 @@ class PythonRepos(Subsystem):
 
             This feature is intended to be used with `[python-repos].find_links`, rather than PEP
             440 direct reference requirements (see
-            {doc_url("python-third-party-dependencies#local-requirements")}.
+            {doc_url("docs/python/overview/third-party-dependencies#local-requirements")}.
             `[python-repos].find_links` must be configured to a valid absolute path for the
             current machine.
 
             Tip: you can avoid each user needing to manually configure this option and
             `[python-repos].find_links` by using a common file location, along with Pants's
-            interpolation support ({doc_url('options#config-file-interpolation')}. For example,
+            interpolation support ({doc_url('docs/using-pants/key-concepts/options#config-file-interpolation')}. For example,
             in `pants.toml`, you could set both options to `%(buildroot)s/python_wheels`
             to point to the directory `python_wheels` in the root of
             your repository; or, use the path `%(env.HOME)s/pants_wheels` for the path
             `~/pants_wheels`. If you are not able to use a common path like this, then we
             recommend setting that each user set these options via a `.pants.rc` file
-            ({doc_url('options#pantsrc-file')}.
+            ({doc_url('docs/using-pants/key-concepts/options#pantsrc-file')}.
 
             Note: Only takes effect if using Pex lockfiles, i.e. using the
             `generate-lockfiles` goal.

src/python/pants/backend/python/subsystems/setup.py

@@ -106,7 +106,7 @@ def interpreter_constraints(self) -> tuple[str, ...]:
                     if different parts of your codebase run against different python interpreter
                     versions in a single repo.
 
-                    See {doc_url("python-interpreter-compatibility")} for details.
+                    See {doc_url("docs/python/overview/interpreter-compatibility")} for details.
                     """
                 ),
             )
@@ -126,7 +126,7 @@ def interpreter_constraints(self) -> tuple[str, ...]:
             interpreter constraints, update `[python].interpreter_constraints`, the
             `interpreter_constraints` field, and relevant tool options like
             `[isort].interpreter_constraints` to tell Pants which interpreters your code
-            actually uses. See {doc_url('python-interpreter-compatibility')}.
+            actually uses. See {doc_url('docs/python/overview/interpreter-compatibility')}.
 
             All elements must be the minor and major Python version, e.g. `'2.7'` or `'3.10'`. Do
             not include the patch version.
@@ -187,7 +187,7 @@ def interpreter_constraints(self) -> tuple[str, ...]:
                 resolve with the `resolve` field.
 
             If a target can work with multiple resolves, you can either use the `parametrize`
-            mechanism or manually create a distinct target per resolve. See {doc_url("targets")}
+            mechanism or manually create a distinct target per resolve. See {doc_url("docs/using-pants/key-concepts/targets-and-build-files")}
             for information about `parametrize`.
 
             For example:
@@ -231,7 +231,7 @@ def interpreter_constraints(self) -> tuple[str, ...]:
             Use this version of Pip for resolving requirements and generating lockfiles.
 
             The value used here must be one of the Pip versions supported by the underlying PEX
-            version. See {doc_url("pex")} for details.
+            version. See {doc_url("docs/python/overview/pex")} for details.
 
             N.B.: The `latest` value selects the latest of the choices listed by PEX which is not
             necessarily the latest Pip version released on PyPI.

src/python/pants/backend/python/subsystems/twine.py

@@ -78,7 +78,7 @@ class TwineSubsystem(PythonToolBase):
 
             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 {doc_url('options')}.
+            environment variable, CLI argument, or `.pants.rc` file. See {doc_url('docs/using-pants/key-concepts/options')}.
             """
         ),
     )

src/python/pants/backend/python/target_types.py

@@ -113,7 +113,7 @@ class InterpreterConstraintsField(StringSequenceField):
 
         If the field is not set, it will default to the option `[python].interpreter_constraints`.
 
-        See {doc_url('python-interpreter-compatibility')} for how these interpreter
+        See {doc_url('docs/python/overview/interpreter-compatibility')} for how these interpreter
         constraints are merged with the constraints of dependencies.
         """
     )
@@ -459,7 +459,7 @@ class PexPlatformsField(StringSequenceField):
         f"""\
     The platforms field is a hack. The abbreviated information it provides is sometimes insufficient,
     leading to hard-to-debug build issues. Use complete_platforms instead.
-    See {doc_url('pex')} for details.
+    See {doc_url('docs/python/overview/pex')} for details.
     """
     )
     help = help_text(
@@ -508,7 +508,7 @@ class PexCompletePlatformsField(SpecialCasedDependencies):
         complete platform JSON as described by Pex
         (https://pex.readthedocs.io/en/latest/buildingpex.html#complete-platform).
 
-        See {doc_url('pex')} for details.
+        See {doc_url('docs/python/overview/pex')} for details.
         """
     )
 
@@ -797,7 +797,7 @@ class PexBinary(Target):
         A Python target that can be converted into an executable PEX file.
 
         PEX files are self-contained executable files that contain a complete Python environment
-        capable of running the target. For more information, see {doc_url('pex')}.
+        capable of running the target. For more information, see {doc_url('docs/python/overview/pex')}.
         """
     )
 
@@ -1059,7 +1059,7 @@ class PythonTestTarget(Target):
         target and then be included in the `dependencies` field. (You can use the
         `python_test_utils` target to generate these `python_source` targets.)
 
-        See {doc_url('python-test-goal')}
+        See {doc_url('docs/python/goals/test')}
         """
     )
 
@@ -1398,7 +1398,7 @@ class PythonRequirementTarget(Target):
         requirement into a `python_requirement` target automatically. For Poetry, use
         `poetry_requirements`.
 
-        See {doc_url('python-third-party-dependencies')}.
+        See {doc_url('docs/python/overview/third-party-dependencies')}.
         """
     )
 
@@ -1443,7 +1443,7 @@ class PythonProvidesField(ScalarField, AsyncFieldMixin):
         in the `setup()` function:
         (https://packaging.python.org/guides/distributing-packages-using-setuptools/#setup-args).
 
-        See {doc_url('plugins-setup-py')} for how to write a plugin to dynamically generate kwargs.
+        See {doc_url('docs/writing-plugins/common-plugin-tasks/custom-python-artifact-kwargs')} for how to write a plugin to dynamically generate kwargs.
         """
     )
 
@@ -1677,7 +1677,7 @@ class PythonDistribution(Target):
         f"""
         A publishable Python setuptools distribution (e.g. an sdist or wheel).
 
-        See {doc_url('python-distributions')}.
+        See {doc_url('docs/python/overview/building-distributions')}.
         """
     )
 
@@ -1786,6 +1786,6 @@ class VCSVersion(Target):
         a subset of that config in this target's fields.
 
         If you need functionality that is not currently exposed here, please reach out to us at
-        {doc_url("getting-help")}.
+        {doc_url("community/getting-help")}.
         """
     )

src/python/pants/backend/python/target_types_rules.py

@@ -423,7 +423,7 @@ async def resolve_python_distribution_entry_points(
                     target type {target.alias}.
 
                     Alternatively, you can use a module like "project.app:main".
-                    See {doc_url('python-distributions')}.
+                    See {doc_url('docs/python/overview/building-distributions')}.
                     """
                 )
             )

src/python/pants/backend/python/typecheck/mypy/subsystem.py

@@ -114,7 +114,7 @@ class MyPy(PythonToolBase):
 
             To instead load third-party plugins, set the option `[mypy].install_from_resolve`
             to a resolve whose lockfile includes those plugins, and set the `plugins` option
-            in `mypy.ini`.  See {doc_url('python-check-goal')}.
+            in `mypy.ini`.  See {doc_url('docs/python/goals/check')}.
             """
         ),
     )
@@ -161,7 +161,7 @@ def check_and_warn_if_python_version_configured(self, config: FileContent | None
                     f"""
                     You set {formatted_configured}. Normally, Pants would automatically set this
                     for you based on your code's interpreter constraints
-                    ({doc_url('python-interpreter-compatibility')}). Instead, it will
+                    ({doc_url('docs/python/overview/interpreter-compatibility')}). Instead, it will
                     use what you set.
 
                     (Allowing Pants to automatically set the option allows Pants to partition your

src/python/pants/backend/python/util_rules/local_dists.py

@@ -73,7 +73,7 @@ async def isolate_local_dist_wheels(
                 code will be used directly from sources, without a distribution being built,
                 and any native extensions in it will not be built.
 
-                See {doc_url('python-distributions')} for details on how to set up a
+                See {doc_url('docs/python/overview/building-distributions')} for details on how to set up a
                 {tgt.target.alias} target to produce a wheel.
                 """
             )

src/python/pants/backend/python/util_rules/local_dists_pep660.py

@@ -281,7 +281,7 @@ async def isolate_local_dist_pep660_wheels(
                 code will be used directly from sources, without a distribution being built,
                 and any native extensions in it will not be built.
 
-                See {doc_url('python-distributions')} for details on how to set up a
+                See {doc_url('docs/python/overview/building-distributions')} for details on how to set up a
                 {tgt.target.alias} target to produce a wheel.
                 """
             )

src/python/pants/backend/python/util_rules/package_dists.py

@@ -94,7 +94,7 @@
 
 class SetupPyError(Exception):
     def __init__(self, msg: str):
-        super().__init__(f"{msg} See {doc_url('python-distributions')}.")
+        super().__init__(f"{msg} See {doc_url('docs/python/overview/building-distributions')}.")
 
 
 class InvalidSetupPyArgs(SetupPyError):
@@ -116,7 +116,7 @@ def __init__(self, msg: str):
         super().__init__(
             softwrap(
                 f"""
-                {msg} See {doc_url('python-distributions')} for
+                {msg} See {doc_url('docs/python/overview/building-distributions')} for
                 how python_sources targets are mapped to distributions.
                 """
             )