docs: implement Starlark domain plugin for Sphinx (#1909)

This implements a Sphinx plugin to support Starlark as a first-class
domain in Sphinx.
A Starlark domain allows writing object descriptions directly using
Sphinx's object
markup language, which allows better integration with cross references,
understanding
and distinguishing types, rendering information about things, and
referencing types
from other projects.

Note that this doesn't affect the docs today because the
proto_to_markdown tool is
still generating regular markdown; updating that to generate Sphinx
domain markdown
will be done separately.

Summary of features:
* Types and arguments can be documented using Python syntax, e.g.
`list[str]` This includes
unions, generics, and custom types. Each component of the type
expression is linked and
cross referenced appropriately. Each object can have its approprate
pieces documented and
defined (e.g. a rule can have attributes, attributes can have their
defaults etc
  documented, etc)
* An index of Starlark objects is generated automatically. This makes it
easy, for example,
  to find the rules that have a particular attribute.
* The following objects can be documented: functions, methods, rules,
repository rules,
providers, aspects, bzlmod extensions, tag classes, targets, flags, and
  attributes/fields of the aforementioned objects.
* Arbitary docs can cross reference to Starlark types. e.g., a manually
written "Getting
Started" doc can write `{bzl:obj}PyInfo.some_field` and it will
automatically link to
  the appropriate API docs.
* Resolution of cross-references is much smarter and customizable.
Instead of relying
Markdown's link resolution rules, the Sphinx's crossreference resolution
hooks are
used. This allows more concise references (e.g., just a rule's base
name), distinguishing
a particular object type (e.g. a function vs rule), or referring to an
absolute object.

docs/sphinx/BUILD.bazel

@@ -70,6 +70,7 @@ sphinx_docs(
 sphinx_inventory(
     name = "bazel_inventory",
     src = "bazel_inventory.txt",
+    visibility = ["//:__subpackages__"],
 )
 
 sphinx_stardocs(

docs/sphinx/bazel_inventory.txt

@@ -2,16 +2,23 @@
 # Project: Bazel
 # Version: 7.0.0
 # The remainder of this file is compressed using zlib
-Action bzl:obj 1 rules/lib/Action -
-File bzl:obj 1 rules/lib/File -
-Label bzl:obj 1 rules/lib/Label -
-Target bzl:obj 1 rules/lib/builtins/Target -
-bool bzl:obj 1 rules/lib/bool -
-depset bzl:obj 1 rules/lib/depset -
-dict bzl:obj 1 rules/lib/dict -
+Action bzl:type 1 rules/lib/Action -
+File bzl:type 1 rules/lib/File -
+Label bzl:type 1 rules/lib/Label -
+Target bzl:type 1 rules/lib/builtins/Target -
+bool bzl:type 1 rules/lib/bool -
+int bzl:type 1 rules/lib/int -
+depset bzl:type 1 rules/lib/depset -
+dict bzl:type 1 rules/lib/dict -
 label bzl:doc 1 concepts/labels -
-list bzl:obj: 1 rules/lib/list -
+attr.bool bzl:type 1 rules/lib/toplevel/attr#bool -
+attr.int bzl:type 1 rules/lib/toplevel/attr#int -
+attr.label bzl:type 1 rules/lib/toplevel/attr#label -
+attr.label_list bzl:type 1 rules/lib/toplevel/attr#label_list -
+attr.string bzl:type 1 rules/lib/toplevel/attr#string -
+attr.string_list bzl:type 1 rules/lib/toplevel/attr#string_list -
+list bzl:type 1 rules/lib/list -
 python bzl:doc 1 reference/be/python -
-str bzl:obj 1 rules/lib/string -
-struct bzl:obj 1 rules/lib/builtins/struct -
+str bzl:type 1 rules/lib/string -
+struct bzl:type 1 rules/lib/builtins/struct -
 target-name bzl:doc 1 concepts/labels#target-names -

docs/sphinx/pyproject.toml

@@ -10,4 +10,5 @@ dependencies = [
     "sphinx_rtd_theme",
     "readthedocs-sphinx-ext",
     "absl-py",
+    "typing-extensions"
 ]

docs/sphinx/requirements.txt

@@ -335,6 +335,10 @@ sphinxcontrib-serializinghtml==1.1.9 \
     --hash=sha256:0c64ff898339e1fac29abd2bf5f11078f3ec413cfe9c046d3120d7ca65530b54 \
     --hash=sha256:9b36e503703ff04f20e9675771df105e58aa029cfcbc23b8ed716019b7416ae1
     # via sphinx
+typing-extensions==4.9.0 \
+    --hash=sha256:23478f88c37f27d76ac8aee6c905017a143b0b1b886c3c9f66bc2fd94f9f5783 \
+    --hash=sha256:af72aea155e91adfc61c3ae9e0e342dbc0cba726d6cba4b6c72c1f34e47291cd
+    # via rules-python-docs (docs/sphinx/pyproject.toml)
 urllib3==2.1.0 \
     --hash=sha256:55901e917a5896a349ff771be919f8bd99aff50b79fe58fec595eb37bbc56bb3 \
     --hash=sha256:df7aa8afb0148fa78488e7899b2c59b5f4ffcfa82e6c54ccb9dd37c1d7b52d54

sphinxdocs/BUILD.bazel

@@ -13,6 +13,7 @@
 # limitations under the License.
 
 load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
+load("@bazel_skylib//rules:common_settings.bzl", "bool_flag")
 load("//sphinxdocs/private:sphinx.bzl", "repeated_string_list_flag")
 
 package(
@@ -31,6 +32,15 @@ repeated_string_list_flag(
     build_setting_default = [],
 )
 
+# Whether to add the `-q` arg to Sphinx invocations, which determines if
+# stdout has any output or not (logging INFO messages and progress messages).
+# If true, add `-q`. If false, don't add `-q`. This is mostly useful for
+# debugging invocations or developing extensions.
+bool_flag(
+    name = "quiet",
+    build_setting_default = True,
+)
+
 bzl_library(
     name = "sphinx_bzl",
     srcs = ["sphinx.bzl"],

sphinxdocs/private/sphinx.bzl

@@ -15,6 +15,7 @@
 """Implementation of sphinx rules."""
 
 load("@bazel_skylib//lib:paths.bzl", "paths")
+load("@bazel_skylib//rules:common_settings.bzl", "BuildSettingInfo")
 load("//python:py_binary.bzl", "py_binary")
 load("//python/private:util.bzl", "add_tag", "copy_propagating_kwargs")  # buildifier: disable=bzl-visibility
 
@@ -119,6 +120,7 @@ def sphinx_docs(
         output_group = "html",
         **common_kwargs
     )
+
     py_binary(
         name = name + ".serve",
         srcs = [_SPHINX_SERVE_MAIN_SRC],
@@ -187,6 +189,7 @@ _sphinx_docs = rule(
         ),
         "_extra_defines_flag": attr.label(default = "//sphinxdocs:extra_defines"),
         "_extra_env_flag": attr.label(default = "//sphinxdocs:extra_env"),
+        "_quiet_flag": attr.label(default = "//sphinxdocs:quiet"),
     },
 )
 
@@ -245,7 +248,9 @@ def _run_sphinx(ctx, format, source_path, inputs, output_prefix):
     args = ctx.actions.args()
     args.add("-T")  # Full tracebacks on error
     args.add("-b", format)
-    args.add("-q")  # Suppress stdout informational text
+
+    if ctx.attr._quiet_flag[BuildSettingInfo].value:
+        args.add("-q")  # Suppress stdout informational text
     args.add("-j", "auto")  # Build in parallel, if possible
     args.add("-E")  # Don't try to use cache files. Bazel can't make use of them.
     args.add("-a")  # Write all files; don't try to detect "changed" files

sphinxdocs/src/sphinx_stardoc/BUILD.bazel

@@ -0,0 +1,14 @@
+load("//python:py_library.bzl", "py_library")
+
+package(
+    default_visibility = ["//:__subpackages__"],
+)
+
+# NOTE: This provides the library on its own, not its dependencies.
+py_library(
+    name = "sphinx_stardoc",
+    srcs = glob(["*.py"]),
+    imports = [".."],
+    # Allow depending on it in sphinx_binary targets
+    visibility = ["//visibility:public"],
+)