Update doc_url calls for new website (#20583)

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>

Author: huonw

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