Use Org Mode for hand-written and generated documentation

.gitattributes

@@ -1,4 +1,4 @@
-# Copyright 2021 Google LLC
+# Copyright 2021, 2022 Google LLC
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -20,4 +20,4 @@ WORKSPACE     text eol=lf
 
 # We enforce Unix-style line endings for the Stardoc files to address
 # https://github.com/bazelbuild/stardoc/issues/110.
-/docs/*.md    text eol=lf
+/docs/*.org   text eol=lf

README.org

@@ -0,0 +1 @@
+docs/index.org

build.py

@@ -143,7 +143,7 @@ def docs(self) -> None:
         """Build the generated documentation files."""
         output = self._run(
             [str(self._bazel_program), 'query', '--output=label',
-             r'filter("\.md\.generated$", kind("generated file", //...:*))'],
+             r'filter("\.org\.generated$", kind("generated file", //...:*))'],
             capture_stdout=True)
         targets = output.splitlines()
         bazel_bin = self._cwd / 'bazel-bin'

docs/BUILD

@@ -1,4 +1,4 @@
-# Copyright 2020, 2021 Google LLC
+# Copyright 2020, 2021, 2022 Google LLC
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -12,13 +12,16 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+load("@bazel_skylib//rules:copy_file.bzl", "copy_file")
 load("@bazel_skylib//rules:diff_test.bzl", "diff_test")
 load("@bazel_skylib//rules:run_binary.bzl", "run_binary")
 load("@io_bazel_stardoc//stardoc:stardoc.bzl", "stardoc")
+load("@com_google_protobuf//:protobuf.bzl", "py_proto_library")
 
 stardoc(
     name = "elisp_doc",
-    out = "elisp_doc.md",
+    out = "elisp_doc.bin",
+    format = "proto",
     input = "//elisp:defs.bzl",
     deps = [
         "//elisp:util_bzl",
@@ -30,7 +33,8 @@ stardoc(
 
 stardoc(
     name = "emacs_doc",
-    out = "emacs_doc.md",
+    out = "emacs_doc.bin",
+    format = "proto",
     input = "//emacs:defs.bzl",
     deps = [
         "//elisp:builtin_bzl",
@@ -41,7 +45,8 @@ stardoc(
 
 stardoc(
     name = "repositories_doc",
-    out = "repositories_doc.md",
+    out = "repositories_doc.bin",
+    format = "proto",
     input = "//elisp:repositories.bzl",
     deps = ["//elisp:builtin_bzl"],
 )
@@ -53,20 +58,16 @@ DOCS = [
 ]
 
 [
-    # Bazel (including Stardoc) interprets all files as Latin-1,
-    # cf. https://docs.bazel.build/versions/4.1.0/build-ref.html#BUILD_files.
-    # However, our files all use UTF-8, leading to double encoding.  Reverse
-    # that effect here.
     run_binary(
-        name = "reencode_" + doc,
-        srcs = [doc + "_doc.md"],
-        outs = [doc + ".md.generated"],
+        name = "gen_" + doc,
+        srcs = [doc + "_doc.bin"],
+        outs = [doc + ".org.generated"],
         args = [
             "--",
-            "$(location :{}_doc.md)".format(doc),
-            "$(location :{}.md.generated)".format(doc),
+            "$(location :{}_doc.bin)".format(doc),
+            "$(location :{}.org.generated)".format(doc),
         ],
-        tool = ":reencode",
+        tool = ":org",
     )
     for doc in DOCS
 ]
@@ -75,15 +76,30 @@ DOCS = [
     diff_test(
         name = doc + "_test",
         size = "small",
-        file1 = doc + ".md",
-        file2 = doc + ".md.generated",
+        file1 = doc + ".org",
+        file2 = doc + ".org.generated",
     )
     for doc in DOCS
 ]
 
 py_binary(
-    name = "reencode",
-    srcs = ["reencode.py"],
+    name = "org",
+    srcs = ["org.py"],
     python_version = "PY3",
     srcs_version = "PY3",
+    tags = ["no-pytype"],  # FIXME
+    deps = [":stardoc_output_py_proto"],
+)
+
+py_proto_library(
+    name = "stardoc_output_py_proto",
+    srcs = [":stardoc_output.proto"],
+    srcs_version = "PY3",
+    tags = ["no-python-check"],
+)
+
+copy_file(
+    name = "copy_stardoc_output_proto",
+    src = "@io_bazel_stardoc//stardoc/proto:stardoc_output.proto",
+    out = "stardoc_output.proto",
 )