docs: fix crossrefs and allow function parameters to be referenced (#…

…1585)

This fixes several old cross references from when the docs were plain
stardoc generated markdown files.

Also fixes how function parameters create their reference name so they
can be referenced.

Also formats conf.py to reduce future diffs. The only semantic change to
conf.py is
removing the suppressing of warnings.

docs/sphinx/_includes/py_console_script_binary.md

@@ -60,5 +60,5 @@ py_console_script_binary(
 ```
 
 [specification]: https://packaging.python.org/en/latest/specifications/entry-points/
-[`py_console_script_binary.binary_rule`]: #py_console_script_binary-binary_rule
+[`py_console_script_binary.binary_rule`]: #py_console_script_binary_binary_rule
 

docs/sphinx/conf.py

@@ -32,25 +32,29 @@
 # Adapted from the template code:
 # https://github.com/readthedocs/readthedocs.org/blob/main/readthedocs/doc_builder/templates/doc_builder/conf.py.tmpl
 if os.environ.get("READTHEDOCS") == "True":
-  # Must come first because it can interfere with other extensions, according
-  # to the original conf.py template comments
-  extensions.insert(0, "readthedocs_ext.readthedocs")
-
-  if os.environ.get("READTHEDOCS_VERSION_TYPE") == "external":
-    # Insert after the main extension
-    extensions.insert(1, "readthedocs_ext.external_version_warning")
-    readthedocs_vcs_url = "http://github.com/bazelbuild/rules_python/pull/{}".format(
-        os.environ.get("READTHEDOCS_VERSION", "")
-    )
-    # The build id isn't directly available, but it appears to be encoded
-    # into the host name, so we can parse it from that. The format appears
-    # to be `build-X-project-Y-Z`, where:
-    # * X is an integer build id
-    # * Y is an integer project id
-    # * Z is the project name
-    _build_id = os.environ.get("HOSTNAME", "build-0-project-0-rules-python")
-    _build_id = _build_id.split("-")[1]
-    readthedocs_build_url = f"https://readthedocs.org/projects/rules-python/builds/{_build_id}"
+    # Must come first because it can interfere with other extensions, according
+    # to the original conf.py template comments
+    extensions.insert(0, "readthedocs_ext.readthedocs")
+
+    if os.environ.get("READTHEDOCS_VERSION_TYPE") == "external":
+        # Insert after the main extension
+        extensions.insert(1, "readthedocs_ext.external_version_warning")
+        readthedocs_vcs_url = (
+            "http://github.com/bazelbuild/rules_python/pull/{}".format(
+                os.environ.get("READTHEDOCS_VERSION", "")
+            )
+        )
+        # The build id isn't directly available, but it appears to be encoded
+        # into the host name, so we can parse it from that. The format appears
+        # to be `build-X-project-Y-Z`, where:
+        # * X is an integer build id
+        # * Y is an integer project id
+        # * Z is the project name
+        _build_id = os.environ.get("HOSTNAME", "build-0-project-0-rules-python")
+        _build_id = _build_id.split("-")[1]
+        readthedocs_build_url = (
+            f"https://readthedocs.org/projects/rules-python/builds/{_build_id}"
+        )
 
 exclude_patterns = ["_includes/*"]
 templates_path = ["_templates"]
@@ -103,22 +107,21 @@
     # * For RTD builds, the flyout menu is always automatically injected,
     #   so having it be True makes the flyout show up twice.
     "READTHEDOCS": False,
-    'PRODUCTION_DOMAIN': "readthedocs.org",
+    "PRODUCTION_DOMAIN": "readthedocs.org",
     # This is the path to a page's source (after the github user/repo/commit)
     "conf_py_path": "/docs/sphinx/",
-    'github_user': 'bazelbuild',
-    'github_repo': 'rules_python',
+    "github_user": "bazelbuild",
+    "github_repo": "rules_python",
     # The git version that was checked out, e.g. the tag or branch name
-    'github_version': os.environ.get("READTHEDOCS_GIT_IDENTIFIER", ""),
+    "github_version": os.environ.get("READTHEDOCS_GIT_IDENTIFIER", ""),
     # For local builds, the github link won't work. Disabling it replaces
     # it with a "view source" link to view the source Sphinx saw, which
     # is useful for local development.
-    'display_github': os.environ.get("READTHEDOCS") == "True",
-    'commit': os.environ.get("READTHEDOCS_GIT_COMMIT_HASH", "unknown commit"),
-
+    "display_github": os.environ.get("READTHEDOCS") == "True",
+    "commit": os.environ.get("READTHEDOCS_GIT_COMMIT_HASH", "unknown commit"),
     # Used by readthedocs_ext.external_version_warning extension
     # This is the PR number being built
-    'current_version': os.environ.get("READTHEDOCS_VERSION", ""),
+    "current_version": os.environ.get("READTHEDOCS_VERSION", ""),
 }
 
 # Keep this in sync with the stardoc templates
@@ -136,10 +139,12 @@
 # -- Options for EPUB output
 epub_show_urls = "footnote"
 
-suppress_warnings = ["myst.header", "myst.xref_missing"]
+suppress_warnings = []
+
 
 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'])
+    # 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"])

docs/sphinx/pip.md

@@ -1,10 +1,9 @@
 (pip-integration)=
 # Pip Integration
 
-To pull in dependencies from PyPI, the `pip_parse` macro is used.
+To pull in dependencies from PyPI, the `pip_parse` function is used, which
+invokes `pip` to download and install dependencies from PyPI.
 
-
-This macro wraps the [`pip_repository`](./pip_repository.md) rule that invokes `pip`.
 In your WORKSPACE file:
 
 ```starlark

docs/sphinx/pypi-dependencies.md

@@ -3,8 +3,9 @@
 Using PyPI packages (aka "pip install") involves two main steps.
 
 1. [Installing third party packages](#installing-third-party-packages)
-2. [Using third party packages as dependencies](#using-third-party-packages-as-dependencies)
+2. [Using third party packages as dependencies](#using-third-party-packages)
 
+{#installing-third-party-packages}
 ## Installing third party packages
 
 ### Using bzlmod
@@ -77,6 +78,7 @@ transition. Still, some users of `pip_install` will need to replace their
 existing `requirements.txt` with a fully resolved set of dependencies using a
 tool such as `pip-tools` or the `compile_pip_requirements` repository rule.
 
+{#using-third-party-packages}
 ## Using third party packages as dependencies
 
 Each extracted wheel repo contains a `py_library` target representing

python/packaging.bzl

@@ -66,7 +66,7 @@ This also has the advantage that stamping information is included in the wheel's
     implementation = _py_wheel_dist_impl,
     attrs = {
         "out": attr.string(doc = "name of the resulting directory", mandatory = True),
-        "wheel": attr.label(doc = "a [py_wheel rule](/docs/packaging.md#py_wheel_rule)", providers = [PyWheelInfo]),
+        "wheel": attr.label(doc = "a [py_wheel target](#py_wheel)", providers = [PyWheelInfo]),
     },
 )
 
@@ -115,9 +115,9 @@ def py_wheel(name, twine = None, publish_args = [], **kwargs):
     )
     ```
 
-    To publish the wheel to Pypi, the twine package is required.
-    rules_python doesn't provide twine itself, see https://github.com/bazelbuild/rules_python/issues/1016
-    However you can install it with pip_parse, just like we do in the WORKSPACE file in rules_python.
+    To publish the wheel to PyPI, the twine package is required.
+    rules_python doesn't provide twine itself, see [https://github.com/bazelbuild/rules_python/issues/1016].
+    However you can install it with [pip_parse](#pip_parse), just like we do in the WORKSPACE file in rules_python.
 
     Once you've installed twine, you can pass its label to the `twine` attribute of this macro,
     to get a "[name].publish" target.

python/pip.bzl

@@ -37,7 +37,7 @@ def pip_install(requirements = None, name = "pip", allow_pip_install = False, **
         requirements (Label): A 'requirements.txt' pip requirements file.
         name (str, optional): A unique name for the created external repository (default 'pip').
         allow_pip_install (bool, optional): change this to keep this rule working (default False).
-        **kwargs (dict): Additional arguments to the [`pip_repository`](./pip_repository.md) repository rule.
+        **kwargs (dict): Additional arguments to the [`pip_parse`](#pip_parse) repository rule.
     """
 
     if allow_pip_install:

python/pip_install/pip_repository.bzl

@@ -586,7 +586,6 @@ pip_repository = repository_rule(
 Those dependencies become available in a generated `requirements.bzl` file.
 You can instead check this `requirements.bzl` file into your repo, see the "vendoring" section below.
 
-This macro wraps the [`pip_repository`](./pip_repository.md) rule that invokes `pip`.
 In your WORKSPACE file:
 
 ```starlark

python/private/py_wheel.bzl

@@ -106,10 +106,10 @@ For example:
 Note that Bazel's output filename cannot include the stamp information, as outputs must be known
 during the analysis phase and the stamp data is available only during the action execution.
 
-The [`py_wheel`](/docs/packaging.md#py_wheel) macro produces a `.dist`-suffix target which creates a
+The [`py_wheel`](#py_wheel) macro produces a `.dist`-suffix target which creates a
 `dist/` folder containing the wheel with the stamped name, suitable for publishing.
 
-See [`py_wheel_dist`](/docs/packaging.md#py_wheel_dist) for more info.
+See [`py_wheel_dist`](#py_wheel_dist) for more info.
 """,
     ),
     "_stamp_flag": attr.label(
@@ -509,7 +509,7 @@ tries to locate `.runfiles` directory which is not packaged in the wheel.
 py_wheel = rule(
     implementation = py_wheel_lib.implementation,
     doc = """\
-Internal rule used by the [py_wheel macro](/docs/packaging.md#py_wheel).
+Internal rule used by the [py_wheel macro](#py_wheel).
 
 These intentionally have the same name to avoid sharp edges with Bazel macros.
 For example, a `bazel query` for a user's `py_wheel` macro expands to `py_wheel` targets,

sphinxdocs/private/func_template.vm

@@ -32,8 +32,9 @@ ${funcInfo.docString}
 {.params-box}
 #end
 ## The .span wrapper is necessary so the trailing colon doesn't wrap
-:[${param.name}[¶](#$link){.headerlink}]{.span}: []{#$link}
-#if(!$param.getDefaultValue().isEmpty())(_default `${param.getDefaultValue()}`_) #end
+:[${param.name}[¶](#$link){.headerlink}]{.span}:
+  {#$link}
+#if(!$param.getDefaultValue().isEmpty())  (_default `${param.getDefaultValue()}`_) #end
 #if(!$param.docString.isEmpty())
   $param.docString.replaceAll("$nl", "$nl  ")
 #else

sphinxdocs/private/provider_template.vm

@@ -19,6 +19,7 @@ ${providerInfo.providerName}(## Comment to consume newline
 $providerInfo.docString
 
 #if ($hasFields)
+{#${pnl}_fields}
 **FIELDS** [¶](#${pnl}_fields){.headerlink}
 
 #foreach ($field in $providerInfo.getFieldInfoList())