docs: convert raw URLs in generated docs and docstrings to hyperlinks

CHANGELOG.md

@@ -721,7 +721,7 @@ Other changes:
 * (core) `#!/usr/bin/env bash` is now used as a shebang in the stage1 bootstrap template.
 * (gazelle:docs) The Gazelle docs have been migrated from {gh-path}`gazelle/README.md` to
   {gh-path}`gazelle/docs` and are now available on the primary documentation site
-  at https://rules-python.readthedocs.io/en/latest/gazelle/docs/index.html
+  at <https://rules-python.readthedocs.io/en/latest/gazelle/docs/index.html>
 
 [20250808]: https://github.com/astral-sh/python-build-standalone/releases/tag/20250808
 
@@ -1133,7 +1133,7 @@ Other changes:
 {#v1-2-0-changed}
 ### Changed
 * (rules) `py_proto_library` is deprecated in favour of the
-  implementation in https://github.com/protocolbuffers/protobuf. It will be
+  implementation in <https://github.com/protocolbuffers/protobuf>. It will be
   removed in the future release.
 * (pypi) {obj}`pip.override` will now be ignored instead of raising an error,
   fixes [#2550](https://github.com/bazel-contrib/rules_python/issues/2550).
@@ -2117,7 +2117,7 @@ Other changes:
   `common --@rules_python//python/config_settings:python_version=X.Y.Z`.
 
 * New Python versions available: `3.11.7`, `3.12.1` using
-  https://github.com/indygreg/python-build-standalone/releases/tag/20240107.
+  <https://github.com/indygreg/python-build-standalone/releases/tag/20240107>.
 
 * (toolchain) Allow setting `x.y` as the `python_version` parameter in
   the version-aware `py_binary` and `py_test` rules. This allows users to
@@ -2269,7 +2269,7 @@ Other changes:
 
 * (docs) bzlmod extensions are now documented on rules-python.readthedocs.io
 * (docs) Support and backwards compatibility policies have been documented.
-  See https://rules-python.readthedocs.io/en/latest/support.html
+  See <https://rules-python.readthedocs.io/en/latest/support.html>
 * (gazelle) `file` generation mode can now also add `__init__.py` to the srcs
   attribute for every target in the package. This is enabled through a separate
   directive `python_generation_mode_per_file_include_init`.
@@ -2401,7 +2401,7 @@ Breaking changes:
   the `py_binary` rule used to build it.
 
 * New Python versions available: `3.8.17`, `3.11.5` using
-  https://github.com/indygreg/python-build-standalone/releases/tag/20230826.
+  <https://github.com/indygreg/python-build-standalone/releases/tag/20230826>.
 
 * (gazelle) New `# gazelle:python_generation_mode file` directive to support
   generating one `py_library` per file.
@@ -2421,7 +2421,7 @@ Breaking changes:
   time being.
 
 * New Python versions available: `3.8.18`, `3.9.18`, `3.10.13`, `3.11.6`, `3.12.0` using
-  https://github.com/indygreg/python-build-standalone/releases/tag/20231002.
+  <https://github.com/indygreg/python-build-standalone/releases/tag/20231002>.
   `3.12.0` support is considered beta and may have issues.
 
 ### Removed

docs/conf.py

@@ -1,6 +1,9 @@
 # Configuration file for the Sphinx documentation builder.
 
 import os
+import re
+
+from docutils import nodes
 
 # -- Project information
 project = "rules_python"
@@ -219,9 +222,19 @@
 ]
 
 
+def _pep_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
+    match = re.search(r"\d+", text)
+    pep_num = match.group(0) if match else text
+    pep_url = f"https://peps.python.org/pep-{pep_num.zfill(4)}/"
+    display_text = text if text.startswith("PEP") else f"PEP {pep_num}"
+    node = nodes.reference(rawtext, display_text, refuri=pep_url, **options)
+    return [node], []
+
+
 def setup(app):
     # Pygments says it supports starlark, but it doesn't seem to actually
     # recognize `starlark` as a name. So just manually map it to python.
     from sphinx.highlighting import lexer_classes
 
     app.add_lexer("starlark", lexer_classes["python"])
+    app.add_role("pep", _pep_role)

docs/extending.md

@@ -23,7 +23,7 @@ Extending the core rules is most useful when you want all or most of the
 behavior of a core rule.
 :::
 
-Follow or comment on https://github.com/bazel-contrib/rules_python/issues/1647
+Follow or comment on {gh-issue}`1647`
 for the development of APIs to support custom derived rules.
 
 ## Creating custom rules

docs/toolchains.md

@@ -473,7 +473,7 @@ pip_parse(
 ```
 
 After registration, your Python targets will use the toolchain's interpreter during execution, but a system-installed interpreter
-is still used to "bootstrap" Python targets (see https://github.com/bazel-contrib/rules_python/issues/691).
+is still used to "bootstrap" Python targets (see {gh-issue}`691`).
 You may also find some quirks while using this toolchain. Please refer to [python-build-standalone documentation's _Quirks_ section](https://gregoryszorc.com/docs/python-build-standalone/main/quirks.html).
 
 ## Local toolchain

gazelle/docs/directives.md

@@ -837,7 +837,7 @@ Version 1.9.0 includes a fix ({gh-pr}`3498`) for a long-standing issue
 ({gh-issue}`3497`) where ancestor `conftest.py` files were not automatically
 added as dependencies of {bzl:obj}`py_test` targets.
 
-However, some people may not want this behavior (see https://xkcd.com/1172/).
+However, some people may not want this behavior (see <https://xkcd.com/1172/>).
 Thus the `python_include_ancestor_conftest` directive controls this behavior.
 It defaults to `true`, which causes all ancestor `conftest.py` files to be
 included as dependencies for {bzl:obj}`py_test` targets.

python/packaging.bzl

@@ -63,7 +63,7 @@ py_wheel_dist = rule(
     doc = """\
 Prepare a dist/ folder, following Python's packaging standard practice.
 
-See https://packaging.python.org/en/latest/tutorials/packaging-projects/#generating-distribution-archives
+See <https://packaging.python.org/en/latest/tutorials/packaging-projects/#generating-distribution-archives>
 which recommends a dist/ folder containing the wheel file(s), source distributions, etc.
 
 This also has the advantage that stamping information is included in the wheel's filename.
@@ -94,7 +94,7 @@ def py_wheel(
         **kwargs):
     """Builds a Python Wheel.
 
-    Wheels are Python distribution format defined in https://www.python.org/dev/peps/pep-0427/.
+    Wheels are Python distribution format defined in {pep}`PEP 427`.
 
     This macro packages a set of targets into a single wheel.
     It wraps the [py_wheel rule](#py_wheel_rule).
@@ -144,7 +144,7 @@ def py_wheel(
     To publish the wheel to PyPI, the twine package is required and it is installed
     by default on `bzlmod` setups. On legacy `WORKSPACE`, `rules_python`
     doesn't provide `twine` itself
-    (see https://github.com/bazel-contrib/rules_python/issues/1016), but
+    (see {gh-issue}`1016`), but
     you can install it with `pip_parse`, just like we do any other dependencies.
 
     Once you've installed twine, you can pass its label to the `twine`
@@ -160,7 +160,7 @@ def py_wheel(
     )
     ```
 
-    Now you can run a command like the following, which publishes to https://test.pypi.org/
+    Now you can run a command like the following, which publishes to <https://test.pypi.org/>
 
     ```sh
     % TWINE_USERNAME=__token__ TWINE_PASSWORD=pypi-*** \\
@@ -172,7 +172,7 @@ def py_wheel(
         name:  A unique name for this target.
         twine: A label of the external location of the py_library target for twine
         twine_binary: A label of the external location of a binary target for twine.
-        publish_args: arguments passed to twine, e.g. ["--repository-url", "https://pypi.my.org/simple/"].
+        publish_args: arguments passed to twine, e.g. `["--repository-url", "https://pypi.my.org/simple/"]`.
             These are subject to make var expansion, as with the `args` attribute.
             Note that you can also pass additional args to the bazel run command as in the example above.
         **kwargs: other named parameters passed to the underlying [py_wheel rule](#py_wheel_rule)

python/private/attributes.bzl

@@ -271,7 +271,7 @@ source files. Possible values are:
   the source file. This is most useful when the code won't be modified.
 
 For more information on pyc invalidation modes, see
-https://docs.python.org/3/library/py_compile.html#py_compile.PycInvalidationMode
+<https://docs.python.org/3/library/py_compile.html#py_compile.PycInvalidationMode>
 """,
             default = PrecompileInvalidationModeAttr.AUTO,
             values = sorted(PrecompileInvalidationModeAttr.__members__.values()),
@@ -281,7 +281,7 @@ https://docs.python.org/3/library/py_compile.html#py_compile.PycInvalidationMode
 The optimization level for precompiled files.
 
 For more information about optimization levels, see the `compile()` function's
-`optimize` arg docs at https://docs.python.org/3/library/functions.html#compile
+`optimize` arg docs at <https://docs.python.org/3/library/functions.html#compile>
 
 NOTE: The value `-1` means "current interpreter", which will be the interpreter
 used _at build time when pycs are generated_, not the interpreter used at
@@ -422,7 +422,7 @@ These values are transitioned on, so will affect the analysis graph and the
 associated memory overhead. The more unique configurations in your overall
 build, the more memory and (often unnecessary) re-analysis and re-building
 can occur. See
-https://bazel.build/extending/config#memory-performance-considerations for
+<https://bazel.build/extending/config#memory-performance-considerations> for
 more information about risks and considerations.
 :::
 

python/private/py_cc_toolchain_info.bzl

@@ -105,7 +105,7 @@ If available, information about C libraries, struct with fields:
         "platform_machine": """
 :type: str
 
-The [PEP 508](https://peps.python.org/pep-0508/) `platform_machine` marker
+The {pep}`PEP 508` `platform_machine` marker
 value for the target architecture, e.g. 'x86_64', 'aarch64'.
 """,
         "platform_tag": """\
@@ -122,7 +122,7 @@ The Python Major.Minor version.
         "sys_platform": """
 :type: str
 
-The [PEP 508](https://peps.python.org/pep-0508/) `sys_platform` marker value
+The {pep}`0508` `sys_platform` marker value
 for the target OS, e.g. 'linux', 'darwin', 'win32'.
 """,
     },

python/private/py_cc_toolchain_rule.bzl

@@ -15,7 +15,7 @@
 """Implementation of py_cc_toolchain rule.
 
 NOTE: This is a beta-quality feature. APIs subject to change until
-https://github.com/bazel-contrib/rules_python/issues/824 is considered done.
+{gh-issue}`824` is considered done.
 """
 
 load("@bazel_skylib//rules:common_settings.bzl", "BuildSettingInfo")

python/private/py_exec_tools_info.bzl

@@ -41,7 +41,7 @@ toolchain.
 :::{warning}
 This does not work correctly with RBE. Use {obj}`exec_runtime` instead.
 
-Once https://github.com/bazelbuild/bazel/issues/23620 is resolved this warning
+Once [bazelbuild/bazel#23620](https://github.com/bazelbuild/bazel/issues/23620) is resolved this warning
 may be removed.
 :::
 """,

python/private/py_executable.bzl

@@ -98,7 +98,7 @@ EXECUTABLE_ATTRS = dicts.add(
 Arguments that are only applicable to the interpreter.
 
 The args an interpreter supports are specific to the interpreter. For
-CPython, see https://docs.python.org/3/using/cmdline.html.
+CPython, see <https://docs.python.org/3/using/cmdline.html>.
 
 :::{note}
 Only supported for {obj}`--bootstrap_impl=script`. Ignored otherwise.
@@ -147,7 +147,7 @@ Module name to execute as the main program.
 When set, `srcs` is not required, and it is assumed the module is
 provided by a dependency.
 
-See https://docs.python.org/3/using/cmdline.html#cmdoption-m for more
+See <https://docs.python.org/3/using/cmdline.html#cmdoption-m> for more
 information about running modules as the main program.
 
 This is mutually exclusive with {obj}`main`.

python/private/py_runtime_rule.bzl

@@ -422,7 +422,7 @@ The template to use when two stage bootstrapping is enabled
 "Shebang" expression prepended to the bootstrapping Python stub script
 used when executing {rule}`py_binary` targets.
 
-See https://github.com/bazelbuild/bazel/issues/8685 for
+See [bazelbuild/bazel#8685](https://github.com/bazelbuild/bazel/issues/8685) for
 motivation.
 
 Does not apply to Windows.

python/private/py_wheel.bzl

@@ -54,7 +54,7 @@ Workspace status keys are expanded using `{NAME}` format, for example:
  - `distribution = "package.{CLASSIFIER}"`
  - `distribution = "{DISTRIBUTION}"`
 
-For the available keys, see https://bazel.build/docs/user-manual#workspace-status
+For the available keys, see <https://bazel.build/docs/user-manual#workspace-status>
 """,
     ),
     "platform": attr.string(
@@ -196,7 +196,7 @@ The {attr}`add_path_prefix` attribute was added.
         default = "",
     ),
     "classifiers": attr.string_list(
-        doc = "A list of strings describing the categories for the package. For valid classifiers see https://pypi.org/classifiers",
+        doc = "A list of strings describing the categories for the package. For valid classifiers see <https://pypi.org/classifiers>",
     ),
     "data_files": attr.label_keyed_string_dict(
         doc = ("""
@@ -233,7 +233,7 @@ be moved under that directory.
     "description_content_type": attr.string(
         doc = ("The type of contents in description_file. " +
                "If not provided, the type will be inferred from the extension of description_file. " +
-               "Also see https://packaging.python.org/en/latest/specifications/core-metadata/#description-content-type"),
+               "Also see <https://packaging.python.org/en/latest/specifications/core-metadata/#description-content-type>"),
     ),
     "description_file": attr.label(
         doc = "A file containing text describing the package.",
@@ -332,7 +332,7 @@ def _escape_filename_distribution_name(name):
 def _escape_filename_segment(segment):
     """Escape a segment of the wheel filename.
 
-    See https://www.python.org/dev/peps/pep-0427/#escaping-and-unicode
+    See {pep}`PEP 427`
     """
 
     # TODO: this is wrong, isalnum replaces non-ascii letters, while we should

python/private/pypi/BUILD.bazel

@@ -522,6 +522,12 @@ bzl_library(
     deps = ["//python/private:envsubst"],
 )
 
+bzl_library(
+    name = "index_sources",
+    srcs = ["index_sources.bzl"],
+    deps = [":hash"],
+)
+
 bzl_library(
     name = "argparse",
     srcs = ["argparse.bzl"],
@@ -542,12 +548,6 @@ bzl_library(
     srcs = ["hash.bzl"],
 )
 
-bzl_library(
-    name = "index_sources",
-    srcs = ["index_sources.bzl"],
-    deps = [":hash"],
-)
-
 bzl_library(
     name = "labels",
     srcs = ["labels.bzl"],

python/private/pypi/extension.bzl

@@ -690,7 +690,7 @@ This value is going to be subject to `envsubst` substitutions if necessary, look
 {attr}`pip.parse.envsubst` documentation for more information..
 
 The indexes must support Simple API as described here:
-https://packaging.python.org/en/latest/specifications/simple-repository-api/
+<https://packaging.python.org/en/latest/specifications/simple-repository-api/>
 
 Index metadata will be used to get the hash digest values for packages even
 if the `--hash` values are not present in the requirements.txt lock file.
@@ -867,10 +867,10 @@ index URL.
 
 This design pattern has been chosen in order to be fully deterministic about which
 packages come from which source. We want to avoid issues similar to what happened in
-https://pytorch.org/blog/compromised-nightly-dependency/.
+<https://pytorch.org/blog/compromised-nightly-dependency/>.
 
 The indexes must support Simple API as described here:
-https://packaging.python.org/en/latest/specifications/simple-repository-api/
+<https://packaging.python.org/en/latest/specifications/simple-repository-api/>
 """,
         ),
         "hub_name": attr.string(

python/private/pypi/pip_compile.bzl

@@ -69,12 +69,12 @@ def pip_compile(
             defaults to `["pyproject.toml"]`. Supported formats are:
             * a requirements text file, usually named `requirements.in`
             * A `.toml` file, where the `project.dependencies` list is used as per
-              [PEP621](https://peps.python.org/pep-0621/).
+              {pep}`PEP 621`.
         src: file containing inputs to dependency resolution. If not specified,
             defaults to `pyproject.toml`. Supported formats are:
             * a requirements text file, usually named `requirements.in`
             * A `.toml` file, where the `project.dependencies` list is used as per
-              [PEP621](https://peps.python.org/pep-0621/).
+              {pep}`PEP 621`.
         extra_args: passed to pip-compile (aka `piptools`). See the
             [pip-compile docs](https://pip-tools.readthedocs.io/en/latest/cli/pip-compile)
             for args and meaning (passing `-h` and/or `--version` can help

python/private/pypi/pip_repository.bzl

@@ -360,13 +360,13 @@ In some cases you may not want to generate the requirements.bzl file as a reposi
 while Bazel is fetching dependencies. For example, if you produce a reusable Bazel module
 such as a ruleset, you may want to include the requirements.bzl file rather than make your users
 install the WORKSPACE setup to generate it.
-See https://github.com/bazel-contrib/rules_python/issues/608
+See {gh-issue}`608`
 
 This is the same workflow as Gazelle, which creates `go_repository` rules with
 [`update-repos`](https://github.com/bazelbuild/bazel-gazelle#update-repos)
 
 To do this, use the "write to source file" pattern documented in
-https://blog.aspect.dev/bazel-can-write-to-the-source-folder
+<https://blog.aspect.dev/bazel-can-write-to-the-source-folder>
 to put a copy of the generated requirements.bzl into your project.
 Then load the requirements.bzl file directly rather than from the generated repository.
 See the example in rules_python/examples/pip_parse_vendored.

python/private/zipapp/py_zipapp_rule.bzl

@@ -344,7 +344,7 @@ These values are transitioned on, so will affect the analysis graph and the
 associated memory overhead. The more unique configurations in your overall
 build, the more memory and (often unnecessary) re-analysis and re-building
 can occur. See
-https://bazel.build/extending/config#memory-performance-considerations for
+<https://bazel.build/extending/config#memory-performance-considerations> for
 more information about risks and considerations.
 :::
 """,

python/runfiles/runfiles.py

@@ -614,7 +614,7 @@ def CurrentRepository(self, frame: int = 1) -> str:
 
         More information about the difference between canonical repository
         names and the `@repo` part of labels is available at:
-        https://bazel.build/build/bzlmod#repository-names
+        <https://bazel.build/build/bzlmod#repository-names>
 
         NOTE: This function inspects the callstack to determine where in the
         runfiles the caller is located to determine which repository it came