docs: convert raw URLs in generated docs and docstrings to hyperlinks (bazel-contrib#3987)

Plain text URLs in documentation Markdown files and Starlark/Python
docstrings were rendered as non-clickable text in the generated HTML
output, making navigation cumbersome.

To fix this, raw URLs are converted into MyST autolinks (<https://...>),
Markdown links, and {gh-issue} roles. A custom {pep} Sphinx role is also
introduced in docs/conf.py to dynamically resolve PEP numbers to
https://peps.python.org/pep-XXXX/, and existing PEP references in
docstrings are updated to use {pep}.

Author: rickeylev

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.
 :::
 """,