docs: fix some doc warnings and xrefs

CHANGELOG.md

@@ -767,8 +767,7 @@ Breaking changes:
 
 ### Added
 
-* (bzlmod, entry_point) Added
-  [`py_console_script_binary`](./docs/py_console_script_binary.md), which
+* (bzlmod, entry_point) Added {obj}`py_console_script_binary`, which
   allows adding custom dependencies to a package's entry points and customizing
   the `py_binary` rule used to build it.
 

docs/api/index.md

@@ -2,6 +2,5 @@
 
 ```{toctree}
 :glob:
-*
 */index
 ```

docs/conf.py

@@ -59,7 +59,7 @@
 autodoc2_docstring_parser_regexes = [
     (".*", "myst"),
 ]
-
+ 
 # NOTE: The redirects generation will clobber existing files.
 redirects = {
     "api/tools/precompiler/index": "/api/rules_python/tools/precompiler/index.html",

python/private/pypi/pip_repository.bzl

@@ -326,7 +326,9 @@ alias(
 )
 ```
 
-### Vendoring the requirements.bzl file
+:::{rubric} Vendoring the requirements.bzl file
+:heading-level: 3
+:::
 
 In some cases you may not want to generate the requirements.bzl file as a repository rule
 while Bazel is fetching dependencies. For example, if you produce a reusable Bazel module

sphinxdocs/docs/sphinx-bzl.md

@@ -140,6 +140,16 @@ Refer to a target.
 
 :::{rst:role} bzl:type
 Refer to a type or type expression; can also be used in argument documentation.
+
+```
+def func(arg):
+    """Do stuff
+
+    Args:
+      arg: {type}`int | str` the arg
+    """
+    print(arg + 1)
+```
 :::
 
 ## Special roles
@@ -187,22 +197,6 @@ def func():
 ```
 :::
 
-:::{rst:role} bzl:type
-
-Indicates the type of an argument for a function. Use it in the Args doc of
-a function.
-
-```
-def func(arg):
-    """Do stuff
-
-    Args:
-      arg: {type}`int`
-    """
-    print(arg + 1)
-```
-:::
-
 ## Directives
 
 Most directives are automatically generated by `sphinx_stardoc`. Here, we only