diff options
Diffstat (limited to 'doc_build')
-rw-r--r-- | doc_build/BUILD | 106 | ||||
-rwxr-xr-x | doc_build/merge.py | 86 |
2 files changed, 192 insertions, 0 deletions
diff --git a/doc_build/BUILD b/doc_build/BUILD new file mode 100644 index 0000000..c50e2d4 --- /dev/null +++ b/doc_build/BUILD @@ -0,0 +1,106 @@ +# 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) >$@", + 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", + "//rules/private: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('<li>', '<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) |