Try to make the docs a little better. (#524)

* Try to make the docs a little better.
- Fix stardoc adding <p align=center> in markdown tables.
- Add rough capability to handle macros that wrap a rule.

The wrapping technique is:
- In the wrapping macro, use the docstring  @wraps(some_rule)
- Then we don't emit the docs for the wrapper
- In the docs for some_rule, replace the string "some_rule" with the
  name of the wrapper macro.

It is a first attempt to make things better.  It is crude, but it
mostly works.It is a first attempt to make things better. It is crude, but it mostly works. If Stardoc ever adds this capability [(feature request)[bazelbuild/stardoc#120] we can move to that.

doc_build/BUILD

@@ -11,16 +11,39 @@
 # 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("@bazel_stardoc//stardoc:stardoc.bzl", "stardoc")
+load("@rules_python//python:defs.bzl", "py_library")
 load("//:version.bzl", "version")
 
-# 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
+filegroup(
+    name = "standard_package",
+    srcs = [
+        "BUILD",
+    ] + glob([
+        "*.bzl",
+        "*.py",
+    ]),
+    visibility = ["//distro:__pkg__"],
+)
 
+exports_files(
+    glob([
+        "*.bzl",
+    ]),
+    visibility = [
+        "//distro:__pkg__",
+        "//doc_build:__pkg__",
+    ],
+)
 
 # pairs of rule name and the source file to get it from
 # buildifier: leave-alone, do not sort
@@ -42,9 +65,8 @@ genrule(
     name = "reference",
     srcs = ["%s.md" % rule for rule, _ in ORDER],
     outs = ["reference.md"],
-    # Compensate for https://github.com/bazelbuild/stardoc/issues/118.
-    # Convert escaped HTML <li> back to raw text
-    cmd = "cat $(SRCS) | sed -e 's/&lt;li&gt;/<li>/g' >$@",
+    cmd = "$(location :merge) $(SRCS) >$@",
+    exec_tools = [":merge"],
 )
 
 [
@@ -107,3 +129,11 @@ bzl_library(
     ],
     visibility = ["//visibility:private"],
 )
+
+py_binary(
+    name = "merge",
+    srcs = ["merge.py"],
+    python_version = "PY3",
+    srcs_version = "PY3",
+    visibility = ["//visibility:private"],
+)

doc_build/merge.py

@@ -0,0 +1,79 @@
+#!/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
+
+
+ID_RE = re.compile(r'<a id="#(.*)">')
+WRAPS_RE = re.compile(r'@wraps\((.*)\)')
+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)
+    this_pkg = 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_pkg
+      return
+    # If something wraps me, rewrite myself with the wrapper name.
+    if this_pkg in wrapper_map:
+      content = content.replace(this_pkg, wrapper_map[this_pkg])
+    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'):
+    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)