Merge pull request #67 from aiuto/doc0

Add the doc creation tools which should have been in #65

3 files changed, 192 insertions, 1 deletions

diff --git a/README.md b/README.md
index 463e0b2..1527f74 100644
--- a/README.md
+++ b/README.md
@@ -18,7 +18,7 @@ WARNING: The code here is still in active initial development and will churn a l
 If you want to follow along:
 - Mailing list: [bazel-ssc@bazel.build](https://groups.google.com/a/bazel.build/g/bazel-ssc)  
 - Monthly eng meeting: [calendar link](MjAyMjA4MjJUMTYwMDAwWiBjXzUzcHBwZzFudWthZXRmb3E5NzhxaXViNmxzQGc&tmsrc=c_53pppg1nukaetfoq978qiub6ls%40group.calendar.google.com&scp=ALL)
-- [Latest docs](https://bazelbuild.github.io/rules_license/latest.md)
+- [Latest docs](https://bazelbuild.github.io/rules_license/latest.html)
 
 Background reading:
 These is for learning about the problem space, and our approach to solutions. Concrete specifications will always appear in checked in code rather than documents.
diff --git a/doc_build/BUILD b/doc_build/BUILD
new file mode 100644
index 0000000..5aadfde
--- /dev/null
+++ b/doc_build/BUILD
@@ -0,0 +1,105 @@
+# Copyright 2022 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.
+"""Generate the reference documentation.
+
+How to:
+   bazel build //doc_build:reference
+   cp bazel-bin/doc_build/reference.md docs/latest.md
+   git commit -m 'update docs' docs/latest.md
+"""
+
+load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
+load("@io_bazel_stardoc//stardoc:stardoc.bzl", "stardoc")
+load("@rules_python//python:defs.bzl", "py_library")
+load("//:version.bzl", "version")
+
+package(default_package_metadata = ["//:license", "//:package_info"])
+
+filegroup(
+    name = "standard_package",
+    srcs = [
+        "BUILD",
+    ] + glob([
+        "*.bzl",
+        "*.py",
+    ]),
+    visibility = ["//distro:__pkg__"],
+)
+
+exports_files(
+    glob([
+        "*.bzl",
+    ]),
+    visibility = [
+        "//distro:__pkg__",
+    ],
+)
+
+# pairs of rule name and the source file to get it from
+# Must put macro wrapped rules after their wrapper
+# buildifier: leave-alone, do not sort
+ORDER = [
+    ("license",         "//rules:license.bzl"),
+    ("_license",        "//rules:license.bzl"),
+    ("license_kind",    "//rules:license_kind.bzl"),
+    ("_license_kind",   "//rules:license_kind.bzl"),
+    ("package_info",    "//rules:package_info.bzl"),
+    ("_package_info",   "//rules:package_info.bzl"),
+    ("LicenseInfo",     "//rules:providers.bzl"),
+    ("LicenseKindInfo", "//rules:providers.bzl"),
+    ("PackageInfo",     "//rules:providers.bzl"),
+]
+
+genrule(
+    name = "reference",
+    srcs = ["%s.md" % rule for rule, _ in ORDER],
+    outs = ["reference.md"],
+    cmd = "$(location :merge) $(SRCS) >$@",
+    exec_tools = [":merge"],
+)
+
+[
+    stardoc(
+        name = "%s_gen" % rule,
+        out = "%s.md" % rule,
+        input = src,
+        symbol_names = [
+            rule,
+        ],
+        deps = [":lib_of_everything"],
+    )
+    for rule, src in ORDER
+    if src
+]
+
+# gather all rules that should be documented
+bzl_library(
+    name = "lib_of_everything",
+    srcs = [
+        "//:version.bzl",
+        "//rules:standard_package",
+        # "@bazel_skylib//lib:paths",
+    ],
+    visibility = ["//visibility:public"],
+)
+
+# This is experimental. We are waiting for stardoc to get the features which
+# are done in merge.
+py_binary(
+    name = "merge",
+    srcs = ["merge.py"],
+    python_version = "PY3",
+    srcs_version = "PY3",
+    visibility = ["//visibility:private"],
+)
diff --git a/doc_build/merge.py b/doc_build/merge.py
new file mode 100755
index 0000000..7212f78
--- /dev/null
+++ b/doc_build/merge.py
@@ -0,0 +1,86 @@
+#!/usr/bin/env python3
+# Copyright 2022 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.
+"""merge stardoc output into a single page.
+
+- concatenates files
+- corrects things that stardoc botches
+"""
+
+import re
+import sys
+import typing
+
+
+# I think stardoc changed the format of the id strings. Sigh.
+ID_RE = re.compile(r'<a id="(.*)">')
+ID_OLD_RE = re.compile(r'<a id="#(.*)">')
+WRAPS_RE = re.compile(r'@wraps\((.*)\)')
+SINCE_RE = re.compile(r'@since\(([^)]*)\)')
+CENTER_RE = re.compile(r'<p align="center">([^<]*)</p>')
+
+
+def merge_file(file: str, out, wrapper_map:typing.Dict[str, str]) -> None:
+  with open(file, 'r') as inp:
+    content = inp.read()
+    m = ID_RE.search(content)
+    if not m:
+      m = ID_OLD_RE.search(content)
+    this_rule = m.group(1) if m else None
+    m = WRAPS_RE.search(content)
+    if m:
+      # I wrap something, so don't emit me.
+      wrapper_map[m.group(1)] = this_rule
+      return
+    # If something wraps me, rewrite myself with the wrapper name.
+    if this_rule in wrapper_map:
+      content = content.replace(this_rule, wrapper_map[this_rule])
+    merge_text(content, out)
+
+
+def merge_text(text: str, out) -> None:
+  """Merge a block of text into an output stream.
+
+  Args:
+    text: block of text produced by Starroc.
+    out: an output file stream.
+  """
+  for line in text.split('\n'):
+    line = SINCE_RE.sub(r'<div class="since"><i>Since \1</i></div>', line)
+
+    if line.startswith('| :'):
+      line = fix_stardoc_table_align(line)
+    # Compensate for https://github.com/bazelbuild/stardoc/issues/118.
+    # Convert escaped HTML <li> back to raw text
+    line = line.replace('&lt;li&gt;', '<li>')
+    line = CENTER_RE.sub(r'\1', line)
+    _ = out.write(line)
+    _ = out.write('\n')
+
+
+def fix_stardoc_table_align(line: str) -> str:
+  """Change centered descriptions to left justified."""
+  if line.startswith('| :-------------: | :-------------: '):
+    return '| :------------ | :--------------- | :---------: | :---------: | :----------- |'
+  return line
+
+
+def main(argv: typing.Sequence[str]) -> None:
+  wrapper_map = {}
+  for file in argv[1:]: 
+    merge_file(file, sys.stdout, wrapper_map)
+
+
+if __name__ == '__main__':
+  main(sys.argv)