Merge pull request #28 from rickeylev:sphinx.docs

PiperOrigin-RevId: 527055531

.gitignore

@@ -0,0 +1,5 @@
+# Generated sphinx docs
+docs/_build/
+# Generated API docs
+/docs/source/api/
+!/docs/source/api/index.md

.readthedocs.yaml

@@ -0,0 +1,23 @@
+
+version: 2
+
+formats:
+  - pdf
+  - htmlzip
+
+sphinx:
+  configuration: docs/source/conf.py
+
+build:
+  os: "ubuntu-22.04"
+  tools:
+    python: "3.11"
+    nodejs: "19"
+  jobs:
+    pre_build:
+      - npm install -g @bazel/bazelisk
+      - bazel run //docs:run_sphinx_build
+
+python:
+  install:
+    - requirements: docs/requirements.txt

MODULE.bazel

@@ -4,9 +4,12 @@ module(
     compatibility_level = 1,
 )
 
+bazel_dep(name = "platforms", version = "0.0.6")
 bazel_dep(name = "bazel_skylib", version = "1.3.0")
 bazel_dep(name = "rules_license", version = "0.0.4")
 
+# ===== The rest of these are development dependencies =====
+
 # TODO(https://github.com/bazelbuild/stardoc/issues/117): stardoc doesn't yet
 # work with bzlmod enabled. This defines the repo so load() works.
 bazel_dep(
@@ -15,3 +18,30 @@ bazel_dep(
     dev_dependency = True,
     repo_name = "io_bazel_stardoc",
 )
+bazel_dep(name = "rules_python", version = "0.20.0", dev_dependency = True)
+
+python = use_extension(
+    "@rules_python//python:extensions.bzl",
+    "python",
+    dev_dependency = True,
+)
+python.toolchain(
+    name = "python3_11",
+    python_version = "3.11",
+)
+use_repo(python, "python3_11_toolchains")
+
+register_toolchains(
+    "@python3_11_toolchains//:all",
+)
+
+pip = use_extension(
+    "@rules_python//python:extensions.bzl",
+    "pip",
+    dev_dependency = True,
+)
+pip.parse(
+    name = "docs-pypi",
+    requirements_lock = "//docs:requirements.txt",
+)
+use_repo(pip, "docs-pypi")

WORKSPACE.bazel

@@ -34,3 +34,32 @@ http_archive(
 load("@io_bazel_stardoc//:setup.bzl", "stardoc_repositories")
 
 stardoc_repositories()
+
+http_archive(
+    name = "rules_python",
+    sha256 = "a644da969b6824cc87f8fe7b18101a8a6c57da5db39caa6566ec6109f37d2141",
+    strip_prefix = "rules_python-0.20.0",
+    url = "https://github.com/bazelbuild/rules_python/releases/download/0.20.0/rules_python-0.20.0.tar.gz",
+)
+
+load("@rules_python//python:repositories.bzl", "python_register_toolchains")
+
+python_register_toolchains(
+    name = "python3_11",
+    # Available versions are listed in @rules_python//python:versions.bzl.
+    # We recommend using the same version your team is already standardized on.
+    python_version = "3.11",
+)
+
+load("@python3_11//:defs.bzl", "interpreter")
+load("@rules_python//python:pip.bzl", "pip_parse")
+
+pip_parse(
+    name = "docs-pypi",
+    python_interpreter_target = interpreter,
+    requirements_lock = "//docs:requirements.txt",
+)
+
+load("@docs-pypi//:requirements.bzl", "install_deps")
+
+install_deps()

docgen/BUILD

@@ -1,38 +1,48 @@
-# Generated documentation for the docs/ directory
-
-load("@io_bazel_stardoc//stardoc:stardoc.bzl", "stardoc")
-load("@bazel_skylib//rules:build_test.bzl", "build_test")
+# Copyright 2023 The Bazel Authors. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
 
-stardoc(
-    name = "truth",
-    out = "truth.md",
-    input = "//lib:truth.bzl",
-    tags = ["skip-bzlmod"],
-    deps = ["//lib:truth_bzl"],
-)
+# Generated documentation for the docs/ directory
 
-stardoc(
-    name = "analysis_test",
-    out = "analysis_test.md",
-    input = "//lib:analysis_test.bzl",
-    tags = ["skip-bzlmod"],
-    deps = ["//lib:analysis_test_bzl"],
-)
+load(":docgen.bzl", "sphinx_stardocs")
 
-stardoc(
-    name = "util",
-    out = "util.md",
-    input = "//lib:util.bzl",
-    tags = ["skip-bzlmod"],
-    deps = ["//lib:util_bzl"],
+package(
+    default_applicable_licenses = ["//:package_license"],
+    default_visibility = ["//:__subpackages__"],
 )
 
-build_test(
-    name = "docs_build_test",
-    tags = ["skip-bzlmod"],
-    targets = [
-        ":truth",
-        ":util",
-        ":analysis_test",
+sphinx_stardocs(
+    name = "docs",
+    bzl_libraries = [
+        "//lib:analysis_test_bzl",
+        "//lib:truth_bzl",
+        "//lib:util_bzl",
+        "//lib/private:action_subject_bzl",
+        "//lib/private:bool_subject_bzl",
+        "//lib/private:collection_subject_bzl",
+        "//lib/private:depset_file_subject_bzl",
+        "//lib/private:dict_subject_bzl",
+        "//lib/private:execution_info_subject_bzl",
+        "//lib/private:expect_bzl",
+        "//lib/private:expect_meta_bzl",
+        "//lib/private:file_subject_bzl",
+        "//lib/private:instrumented_files_info_subject_bzl",
+        "//lib/private:int_subject_bzl",
+        "//lib/private:label_subject_bzl",
+        "//lib/private:ordered_bzl",
+        "//lib/private:run_environment_info_subject_bzl",
+        "//lib/private:runfiles_subject_bzl",
+        "//lib/private:str_subject_bzl",
+        "//lib/private:target_subject_bzl",
     ],
 )

docgen/docgen.bzl

@@ -0,0 +1,70 @@
+# Copyright 2023 The Bazel Authors. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Rules to help generate rules_testing docs."""
+
+load("@io_bazel_stardoc//stardoc:stardoc.bzl", "stardoc")
+load("@bazel_skylib//rules:build_test.bzl", "build_test")
+
+def sphinx_stardocs(name, bzl_libraries, **kwargs):
+    """Generate Sphinx-friendly markdown docs using Stardoc for bzl libraries.
+
+    Args:
+        name: str, the name of the resulting file group with the generated docs.
+        bzl_libraries: list of targets, the libraries to generate docs for.
+            The must be in "//foo:{name}_bzl" format; the `{name}` portion
+            will become the output file name.
+        **kwargs: Additional kwargs to pass onto generated targets (e.g.
+            tags)
+    """
+
+    # Stardoc doesn't yet work with bzlmod; we can detect this by
+    # looking for "@@" vs "@" in labels.
+    if "@@" in str(Label("//:X")):
+        kwargs["target_compatible_with"] = ["@platforms//:incompatible"]
+
+    docs = []
+    for label in bzl_libraries:
+        lib_name = Label(label).name.replace("_bzl", "")
+
+        doc_rule_name = "_{}_{}".format(name, lib_name)
+        sphinx_stardoc(
+            name = "_{}_{}".format(name, lib_name),
+            out = lib_name + ".md",
+            input = label.replace("_bzl", ".bzl"),
+            deps = [label],
+            **kwargs
+        )
+        docs.append(doc_rule_name)
+
+    native.filegroup(
+        name = name,
+        srcs = docs,
+        **kwargs
+    )
+    build_test(
+        name = name + "_build_test",
+        targets = docs,
+        **kwargs
+    )
+
+def sphinx_stardoc(**kwargs):
+    stardoc(
+        # copybara-marker: stardoc format
+        func_template = "func_template.vm",
+        header_template = "header_template.vm",
+        rule_template = "rule_template.vm",
+        provider_template = "provider_template.vm",
+        **kwargs
+    )

docgen/func_template.vm

@@ -0,0 +1,56 @@
+#set( $nl = "
+" )
+#set( $fn = $funcInfo.functionName)
+#set( $fnl = $fn.replaceAll("[.]", "_").toLowerCase())
+{.starlark-object}
+#[[##]]# $fn
+
+#set( $hasParams = false)
+{.starlark-signature}
+${funcInfo.functionName}(## Comment to consume newline
+#foreach ($param in $funcInfo.getParameterList())
+#if($param.name != "self")
+#set( $hasParams = true)
+[${param.name}](#${fnl}_${param.name})## Comment to consume newline
+#if(!$param.getDefaultValue().isEmpty())
+=$param.getDefaultValue()#end#if($foreach.hasNext),
+#end
+#end
+#end
+)
+
+${funcInfo.docString}
+
+#if ($hasParams)
+{#${fnl}_parameters}
+**PARAMETERS** [¶](#${fnl}_parameters){.headerlink}
+
+#foreach ($param in $funcInfo.getParameterList())
+#if($param.name != "self")
+#set($link = $fnl + "_" + $param.name)
+#if($foreach.first)
+{.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
+#if(!$param.docString.isEmpty())
+  $param.docString.replaceAll("$nl", "$nl  ")
+#else
+  _undocumented_
+#end
+#end
+#end
+#end
+#if (!$funcInfo.getReturn().docString.isEmpty())
+
+{#${fnl}_returns}
+RETURNS [¶](#${fnl}_returns){.headerlink}
+: ${funcInfo.getReturn().docString.replaceAll("$nl", "$nl  ")}
+#end
+#if (!$funcInfo.getDeprecated().docString.isEmpty())
+
+**DEPRECATED**
+
+${funcInfo.getDeprecated().docString}
+#end

docgen/header_template.vm

@@ -0,0 +1 @@
+$moduleDocstring

docgen/provider_template.vm

@@ -0,0 +1,29 @@
+#set( $nl = "
+" )
+#set( $pn = $providerInfo.providerName)
+#set( $pnl = $pn.replaceAll("[.]", "_").toLowerCase())
+{.starlark-object}
+#[[##]]# ${providerName}
+
+#set( $hasFields = false)
+{.starlark-signature}
+${providerInfo.providerName}(## Comment to consume newline
+#foreach ($field in $providerInfo.getFieldInfoList())
+#set( $hasFields = true)
+[${field.name}](#${pnl}_${field.name})## Comment to consume newline
+#if($foreach.hasNext),
+#end
+#end
+)
+
+$providerInfo.docString
+
+#if ($hasFields)
+**FIELDS** [¶](#${pnl}_fields){.headerlink}
+
+#foreach ($field in $providerInfo.getFieldInfoList())
+#set($link = $pnl + "_" + $field.name)
+:[${field.name}[¶](#$link){.headerlink}]{.span}: []{#$link}
+  $field.docString.replaceAll("$nl", "$nl  ")
+#end
+#end

docgen/rule_template.vm

@@ -0,0 +1,48 @@
+#set( $nl = "
+" )
+#set( $rn = $ruleInfo.ruleName)
+#set( $rnl = $rn.replaceAll("[.]", "_").toLowerCase())
+{.starlark-object}
+#[[##]]# $ruleName
+
+#set( $hasAttrs = false)
+{.starlark-signature}
+${ruleInfo.ruleName}(## Comment to consume newline
+#foreach ($attr in $ruleInfo.getAttributeList())
+#set( $hasAttrs = true)
+[${attr.name}](#${rnl}_${attr.name})## Comment to consume newline
+#if(!$attr.getDefaultValue().isEmpty())
+=$attr.getDefaultValue()#end#if($foreach.hasNext),
+#end
+#end
+)
+
+$ruleInfo.docString
+
+#if ($hasAttrs)
+{#${rnl}_attributes}
+**ATTRIBUTES** [¶](#${rnl}_attributes){.headerlink}
+
+#foreach ($attr in $ruleInfo.getAttributeList())
+#set($link = $rnl + "_" + $attr.name)
+#if($attr.mandatory)
+#set($opt = "required")
+#else
+#set($opt = "optional")
+#end
+#if($attr.type == "NAME")
+#set($type = "[Name][target-name]")
+#elseif($attr.type == "LABEL_LIST")
+#set($type = "list of [label][attr-label]s")
+#end
+#if(!$attr.getDefaultValue().isEmpty())
+#set($default = ", default `" + $attr.getDefaultValue() + "`")
+#else
+#set($default = "")
+#end
+:[${attr.name}[¶](#$link){.headerlink}]{.span}: []{#$link}
+  _($opt $type$default)_
+  $attr.docString.replaceAll("$nl", "$nl  ")
+
+#end
+#end