diff options
author | Tony Aiuto <aiuto@google.com> | 2022-12-16 13:12:48 -0500 |
---|---|---|
committer | Tony Aiuto <aiuto@google.com> | 2022-12-16 13:12:48 -0500 |
commit | b6abe9dc04c0ad96432975c502ea93e9c9c52b59 (patch) | |
tree | 7045e55c744448709be23afb776b0d2494a482aa | |
parent | 7a977d270f554114784c1eec7a5ef0f5aa92be02 (diff) | |
download | bazelbuild-rules_license-b6abe9dc04c0ad96432975c502ea93e9c9c52b59.tar.gz |
wtf happened to doc_build
-rw-r--r-- | doc_build/BUILD | 105 | ||||
-rw-r--r-- | doc_build/common.md | 53 | ||||
-rwxr-xr-x | doc_build/merge.py | 86 | ||||
-rw-r--r-- | doc_build/toc.md.tpl | 28 |
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('<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) 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> |