wtf happened to doc_build

4 files changed, 272 insertions, 0 deletions

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/common.md b/doc_build/common.md
new file mode 100644
index 0000000..d2be5ed
--- /dev/null
+++ b/doc_build/common.md
@@ -0,0 +1,53 @@
+<a name="common"></a>
+
+### Common Attributes
+
+These attributes are used in several rules within this module.
+
+**ATTRIBUTES**
+
+| Name              | Description                                                                                                                                                                     | Type                                                               | Mandatory       | Default                                   |
+| :-------------    | :-------------                                                                                                                                                                  | :-------------:                                                    | :-------------: | :-------------                            |
+| out               | Name of the output file. This file will always be created and used to access the package content. If `package_file_name` is also specified, `out` will be a symlink.            | String                                                             | required        |                                           |
+| package_file_name | The name of the file which will contain the package. The name may contain variables in the forms `{var}` and $(var)`. The values for substitution are specified through `package_variables` or taken from [ctx.var](https://bazel.build/rules/lib/ctx#var). | String | optional | package type specific |
+| package_variables | A target that provides `PackageVariablesInfo` to substitute into `package_file_name`.                                                                                           | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional        | None                                      |
+| attributes        | Attributes to set on entities created within packages.  Not to be confused with bazel rule attributes.  See 'Mapping "Attributes"' below                                        | Undefined.                                                         | optional        | Varies.  Consult individual rule documentation for details. |
+
+See
+[examples/naming_package_files](https://github.com/bazelbuild/rules_pkg/tree/main/examples/naming_package_files)
+for examples of how `out`, `package_file_name`, and `package_variables`
+interact.
+
+@since(0.8.0): File name substitution now supports the $(var) syntax.
+@since(0.8.0): File name substitution now supports direct use of [ctx.var](https://bazel.build/rules/lib/ctx#var).
+
+
+<a name="mapping-attrs"></a>
+### Mapping "Attributes"
+
+The "attributes" attribute specifies properties of package contents as used in
+rules such as `pkg_files`, and `pkg_mkdirs`.  These allow fine-grained control
+of the contents of your package.  For example:
+
+```python
+attributes = pkg_attributes(
+    mode = "0644",
+    user = "root",
+    group = "wheel",
+    my_custom_attribute = "some custom value",
+)
+```
+
+`mode`, `user`, and `group` correspond to common UNIX-style filesystem
+permissions.  Attributes should always be specified using the `pkg_attributes`
+helper macro.
+
+Each mapping rule has some default mapping attributes.  At this time, the only
+default is "mode", which will be set if it is not otherwise overridden by the user.
+
+If `user` and `group` are not specified, then defaults for them will be chosen
+by the underlying package builder.  Any specific behavior from package builders
+should not be relied upon.
+
+Any other attributes should be specified as additional arguments to
+`pkg_attributes`.
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)
diff --git a/doc_build/toc.md.tpl b/doc_build/toc.md.tpl
new file mode 100644
index 0000000..224f363
--- /dev/null
+++ b/doc_build/toc.md.tpl
@@ -0,0 +1,28 @@
+# rules_pkg - {VERSION}
+
+<div class="toc">
+  <h2>Common Attributes</h2>
+  <ul>
+    <li><a href="#common">Package attributes</a></li>
+    <li><a href="#mapping-attrs">File attributes</a></li>
+  </ul>
+
+  <h2>Packaging Rules</h2>
+  <ul>
+    <li><a href="#pkg_deb">//pkg:deb.bzl%pkg_deb</a></li>
+    <li><a href="#pkg_rpm">//pkg:rpm.bzl%pkg_rpm</a></li>
+    <li><a href="#pkg_tar">//pkg:tar.bzl%pkg_tar</a></li>
+    <li><a href="#pkg_zip">//pkg:zip.bzl%pkg_zip</a></li>
+  </ul>
+
+  <h2>File Tree Creation Rules</h2>
+  <ul>
+    <li><a href="#filter_directory">//pkg:mappings.bzl%filter_directory</a></li>
+    <li><a href="#pkg_filegroup">//pkg:mappings.bzl%pkg_filegroup</a></li>
+    <li><a href="#pkg_files">//pkg:mappings.bzl%pkg_files</a></li>
+    <li><a href="#pkg_mkdirs">//pkg:mappings.bzl%pkg_mkdirs</a></li>
+    <li><a href="#pkg_mklink">//pkg:mappings.bzl%pkg_mklink</a></li>
+    <li><a href="#pkg_attributes">//pkg:mappings.bzl%pkg_attributes</a></li>
+    <li><a href="#strip_prefix.files_only">//pkg:mappings.bzl%strip_prefix</a></li>
+  </ul>
+</div>