Document module extensions if possible.

MODULE.bazel

@@ -53,7 +53,7 @@ use_repo(non_module_deps, "gnu_emacs_29.1")
 use_repo(non_module_deps, "phst_rules_elisp_toolchains")
 
 non_module_dev_deps = use_extension("//private:non_module_deps.bzl", "non_module_dev_deps", dev_dependency = True)
-use_repo(non_module_dev_deps, "junit_xsd")
+use_repo(non_module_dev_deps, "junit_xsd", "phst_rules_elisp_bazel_version")
 
 # Local toolchains
 register_toolchains("@phst_rules_elisp//elisp:hermetic_toolchain")

docs/BUILD

@@ -12,9 +12,11 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+load("@bazel_skylib//lib:versions.bzl", "versions")
 load("@bazel_skylib//rules:copy_file.bzl", "copy_file")
 load("@com_google_protobuf//:protobuf.bzl", "py_proto_library")
 load("@io_bazel_stardoc//stardoc:stardoc.bzl", "stardoc")
+load("@phst_rules_elisp_bazel_version//:defs.bzl", "BAZEL_VERSION")
 load("@pip_deps//:requirements.bzl", "requirement")
 load("@rules_python//python:defs.bzl", "py_binary")
 load("//elisp:defs.bzl", "elisp_binary", "elisp_manual")
@@ -41,17 +43,18 @@ genrule(
     cmd = "makeinfo --no-split --output=$@ -- $<",
 )
 
+DOCUMENT_EXTENSIONS = versions.is_at_least("7", BAZEL_VERSION)
+
 DOCS = [
     "elisp",
     "emacs",
     "repositories",
-    # Requires Bazel 7.  See https://github.com/bazelbuild/stardoc/issues/192.
-    # "extensions",
-]
+] + (["extensions"] if DOCUMENT_EXTENSIONS else [])
 
 merged_manual(
     name = "merged_manual",
     out = "merged.org",
+    exclude_tag = "" if DOCUMENT_EXTENSIONS else "extensions",
     includes = DOCS,
     main = "manual.org",
 )
@@ -102,18 +105,23 @@ stardoc(
     ],
 )
 
-# Requires Bazel 7.  See https://github.com/bazelbuild/stardoc/issues/192.
-# stardoc(
-#     name = "extensions",
-#     out = "extensions.bin",
-#     format = "proto",
-#     input = "//elisp:extensions.bzl",
-#     deps = [
-#         "//elisp:builtin_bzl",
-#         "//elisp:repositories_bzl",
-#         "//private:repositories_bzl",
-#     ],
-# )
+stardoc(
+    name = "extensions",
+    out = "extensions.bin",
+    format = "proto",
+    input = "//elisp:extensions.bzl",
+    tags = [
+        # Due to https://github.com/bazelbuild/stardoc/issues/192, building this
+        # target fails on Bazel 6 and below, so don’t include it in target
+        # patterns.
+        "manual",
+    ],
+    deps = [
+        "//elisp:builtin_bzl",
+        "//elisp:repositories_bzl",
+        "//private:repositories_bzl",
+    ],
+)
 
 py_binary(
     name = "generate",

docs/generate.py

@@ -85,6 +85,8 @@ def run(self, module: stardoc_output_pb2.ModuleInfo) -> None:
             self._function(func)
         for aspect in module.aspect_info:
             self._aspect(aspect)
+        for extension in module.module_extension_info:
+            self._extension(extension)
         for rule in module.repository_rule_info:
             self._repo_rule(rule)
 
@@ -157,6 +159,29 @@ def _aspect(self, aspect: stardoc_output_pb2.AspectInfo) -> None:
             self._attribute(attr)
         self._write('#+END_deffn\n\n')
 
+    def _extension(self, ext: stardoc_output_pb2.ModuleExtensionInfo) -> None:
+        name = ext.extension_name
+        tags = ', '.join(t.tag_name for t in ext.tag_class)
+        self._write(
+            f'#+ATTR_TEXINFO: :options {{Module extension}} {name} {tags}\n')
+        self._write('#+BEGIN_deftp\n')
+        self._write(_markdown(ext.doc_string).lstrip())
+        self._write(f'The ~{name}~ module extension '
+                    f'provides the following tag classes:\n\n')
+        for tag in ext.tag_class:
+            attrs = ', '.join(a.name if a.mandatory else f'[{a.name}]'
+                              for a in tag.attribute)
+            self._write(f'#+ATTR_TEXINFO: :options '
+                        f'{{Tag class}} {name} {tag.tag_name} ({attrs})\n')
+            self._write('#+BEGIN_defop\n')
+            self._write(_markdown(tag.doc_string).lstrip())
+            self._write(f'The ~{tag.tag_name}~ tag class '
+                        f'supports the following attributes:\n\n')
+            for attr in tag.attribute:
+                self._attribute(attr)
+            self._write('#+END_defop\n\n')
+        self._write('#+END_deftp\n\n')
+
     def _repo_rule(self, rule: stardoc_output_pb2.RepositoryRuleInfo) -> None:
         name = rule.rule_name
         attrs = ', '.join(a.name if a.mandatory else f'[{a.name}]'

docs/manual.org

@@ -676,6 +676,13 @@ from {{{var(array)}}}.  Elements are shifted left to fill in the hole.
 
 #+INCLUDE: repositories.org
 
+* Symbols defined in =//elisp:extensions.bzl= :extensions:
+:PROPERTIES:
+:ALT_TITLE: Extension Starlark symbols
+:END:
+
+#+INCLUDE: extensions.org
+
 * Symbols defined in =//emacs:defs.bzl=
 :PROPERTIES:
 :ALT_TITLE: Emacs Starlark symbols

docs/merge.el

@@ -1,6 +1,6 @@
 ;;; merge.el --- merge generated documentation into combined manual  -*- lexical-binding: t; -*-
 
-;; Copyright 2021, 2022 Google LLC
+;; Copyright 2021, 2022, 2023 Google LLC
 ;;
 ;; Licensed under the Apache License, Version 2.0 (the "License");
 ;; you may not use this file except in compliance with the License.
@@ -26,7 +26,7 @@
 (unless noninteractive (user-error "This file works only in batch mode"))
 
 (pcase command-line-args-left
-  (`(,output ,main . ,includes)
+  (`(,exclude ,output ,main . ,includes)
    (setq command-line-args-left nil)
    (let ((coding-system-for-read 'utf-8-unix)
          (coding-system-for-write 'utf-8-unix)
@@ -36,9 +36,11 @@
      (with-temp-buffer
        (insert-file-contents main :visit)
        (org-mode)
+       (unless (string-empty-p exclude)
+         (org-map-entries #'org-cut-subtree exclude))
        (org-export-expand-include-keyword nil temp-dir)
        (write-region nil nil output))
      (delete-directory temp-dir :recursive)))
-  (_ (user-error "Usage: docs/merge OUTPUT.org MAIN.org INCLUDE.org…")))
+  (_ (user-error "Usage: docs/merge EXCLUDE OUTPUT.org MAIN.org INCLUDE.org…")))
 
 ;;; merge.el ends here

private/defs.bzl

@@ -471,6 +471,7 @@ def _merged_manual_impl(ctx):
         orgs.append(org)
 
     args = ctx.actions.args()
+    args.add(ctx.attr.exclude_tag)
     args.add(ctx.outputs.out)
     args.add(ctx.file.main)
     args.add_all(orgs, expand_directories = False)
@@ -498,6 +499,7 @@ merged_manual = rule(
             allow_empty = False,
         ),
         "out": attr.output(mandatory = True),
+        "exclude_tag": attr.string(mandatory = True),
         "_generate": attr.label(
             executable = True,
             cfg = "exec",

private/repositories.bzl

@@ -68,6 +68,7 @@ def non_module_dev_deps():
             "https://github.com/windyroad/JUnit-Schema/archive/refs/tags/1.0.0.tar.gz",  # 2022-04-09
         ],
     )
+    _bazel_version(name = "phst_rules_elisp_bazel_version")
 
 def _toolchains_impl(repository_ctx):
     windows = repository_ctx.os.name.startswith("windows")
@@ -78,6 +79,29 @@ _toolchains = repository_rule(
     implementation = _toolchains_impl,
 )
 
+def _bazel_version_impl(repository_ctx):
+    repository_ctx.file(
+        "WORKSPACE.bazel",
+        "workspace(name = %r)\n" % repository_ctx.name,
+        executable = False,
+    )
+    repository_ctx.file(
+        "BUILD.bazel",
+        "",
+        executable = False,
+    )
+    repository_ctx.file(
+        "defs.bzl",
+        "BAZEL_VERSION = %r\n" % native.bazel_version,
+        executable = False,
+    )
+
+_bazel_version = repository_rule(
+    doc = "Workaround for https://github.com/bazelbuild/bazel/issues/8305",
+    implementation = _bazel_version_impl,
+    local = True,  # always reevaluate in case the Bazel version changes
+)
+
 HTTP_ARCHIVE_DOC = """Downloads an archive file over HTTP and makes its contents
 available as an `elisp_library`.  This {kind} is very similar to
 [`http_archive`](https://bazel.build/rules/lib/repo/http#http_archive),