diff options
author | Yifan Hong <elsk@google.com> | 2024-03-21 14:00:36 -0700 |
---|---|---|
committer | Yifan Hong <elsk@google.com> | 2024-03-21 14:00:37 -0700 |
commit | dea7500c20c656dcf2feb34d5583b636af798bef (patch) | |
tree | ace9303555f218821b98e8b62b322e9397356f5c | |
parent | 2a10807a06153b5862da0369f4b6b368afc2dd08 (diff) | |
download | bazel_common_rules-dea7500c20c656dcf2feb34d5583b636af798bef.tar.gz |
Delete bazel_common_rules/docs.
Kleaf was the last user of these rules, and it has
migrated to using stardoc() directly and checking
in the Markdown files to the source tree. With bzlmod,
it is impractical to build stardoc() targets in an
isolated environment without access to the Internet
due to Maven dependencies.
Bug: 329305827
Bug: 324643611
Change-Id: I24e499db8de87fadd1520e40a4d8c19d09512ee4
-rw-r--r-- | docs/BUILD | 21 | ||||
-rw-r--r-- | docs/docs.bzl | 177 | ||||
-rw-r--r-- | docs/index.html | 112 | ||||
-rwxr-xr-x | docs/insert_resource.py | 41 | ||||
-rw-r--r-- | docs/templates/func.vm | 21 | ||||
-rw-r--r-- | docs/templates/provider.vm | 20 | ||||
-rw-r--r-- | docs/templates/rule.vm | 21 |
7 files changed, 0 insertions, 413 deletions
diff --git a/docs/BUILD b/docs/BUILD deleted file mode 100644 index 1d032fb..0000000 --- a/docs/BUILD +++ /dev/null @@ -1,21 +0,0 @@ -# Copyright (C) 2021 The Android Open Source Project -# -# 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. - -exports_files([ - "index.html", - "insert_resource.py", - "templates/func.vm", - "templates/provider.vm", - "templates/rule.vm", -]) diff --git a/docs/docs.bzl b/docs/docs.bzl deleted file mode 100644 index ed25a45..0000000 --- a/docs/docs.bzl +++ /dev/null @@ -1,177 +0,0 @@ -# Copyright (C) 2021 The Android Open Source Project -# -# 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 bare-bones docs with Stardoc""" - -load("@bazel_skylib//:bzl_library.bzl", "bzl_library") -load("@io_bazel_stardoc//stardoc:stardoc.bzl", "stardoc") -load("//build/bazel_common_rules/dist:dist.bzl", "copy_to_dist_dir") - -def _sanitize_label_as_filename(label): - """Sanitize a Bazel label so it is safe to be used as a filename.""" - label_text = str(label) - return _normalize(label_text) - -def _normalize(s): - """Returns a normalized string by replacing non-letters / non-numbers as underscores.""" - return "".join([c if c.isalnum() else "_" for c in s.elems()]) - -# TODO: Add aspect_template when necessary -def docs( - name, - srcs, - default = None, - deps = None, - func_template = None, - provider_template = None, - rule_template = None, - **kwargs): - """Build docs. - - The following rules are also generated: - - `{name}_dist` is created for distribution - - `{name}_server` is created for seeing docs locally. View with - ``` - bazel run {name}_server - ``` - - Args: - name: name of this rule. - srcs: sources (`*.bzl` files) to generate docs. Docs for definitions in - these files are emitted. - - `srcs` must be a list of real files. Labels to rules are not accepted. - default: An element in `srcs` that's shown in the renderer by default. - deps: additional dependencies of `srcs`. Definitions in these files do - not show up in the final output. - func_template: Template for generating docs for functions. - provider_template: Template for generating docs for providers. - rule_template: Template for generating docs for rules. - **kwargs: kwargs to internal rules - """ - - all_deps = [] - all_deps += srcs - if deps != None: - all_deps += deps - - if func_template == None: - func_template = "//build/bazel_common_rules/docs:templates/func.vm" - if provider_template == None: - provider_template = "//build/bazel_common_rules/docs:templates/provider.vm" - if rule_template == None: - rule_template = "//build/bazel_common_rules/docs:templates/rule.vm" - - private_kwargs = kwargs | { - "visibility": ["//visibility:private"], - } - - bzl_library( - name = name + "_deps", - srcs = all_deps, - **private_kwargs - ) - - # Key: label to bzl. Value: label to markdown. - bzl_md = {} - - for src in srcs: - stardoc_target_name = name + "-" + _sanitize_label_as_filename(src) - stardoc( - name = stardoc_target_name, - out = name + "/" + _sanitize_label_as_filename(src) + ".md", - input = src, - deps = [":" + name + "_deps"], - func_template = func_template, - provider_template = provider_template, - rule_template = rule_template, - **private_kwargs - ) - bzl_md[src] = stardoc_target_name - - default_file_cmd = """touch $@ && """ - for src in srcs: - if default == src: - default_file_cmd += """echo '<div hidden><a href="#{src}" id="default_file">{src}</a></div>' >> $@ &&""".format( - src = src, - ) - break - default_file_cmd += ":" - - native.genrule( - name = name + "_default_file.html.frag", - srcs = [ - ], - outs = [ - name + "/docs_resources/default_file.html.frag", - ], - cmd = default_file_cmd, - **private_kwargs - ) - - native.genrule( - name = name, - srcs = [ - "//build/bazel_common_rules/docs:index.html", - ":{name}_default_file.html.frag".format(name = name), - ] + bzl_md.keys() + bzl_md.values(), - outs = [ - name + "/root/index.html", - ], - cmd = """ - $(location //build/bazel_common_rules/docs:insert_resource.py) \\ - --infile $(location //build/bazel_common_rules/docs:index.html) \\ - --outfile $(location {name}/root/index.html) \\ - default_file.html.frag:$(location :{name}_default_file.html.frag) \\ - {bzl_md} - """.format( - name = name, - bzl_md = " ".join(["$(location {}):$(location {})".format(bzl, md) for bzl, md in bzl_md.items()]), - ), - tools = [ - "//build/bazel_common_rules/docs:insert_resource.py", - ], - **kwargs - ) - - native.genrule( - name = name + "_run_server.sh", - srcs = [], - outs = [ - name + "/run_server.sh", - ], - cmd = """ - cat > $(location {name}/run_server.sh) <<< '#!/usr/bin/env sh -cd $$(dirname $$0)/{name}/root && -python3 -m http.server 8080 -' - chmod +x $(location {name}/run_server.sh) - """.format(name = name), - **private_kwargs - ) - - native.sh_binary( - name = name + "_server", - srcs = [ - ":{name}_run_server.sh".format(name = name), - ], - data = [":" + name], - **kwargs - ) - - copy_to_dist_dir( - name = name + "_dist", - data = [":" + name], - **kwargs - ) diff --git a/docs/index.html b/docs/index.html deleted file mode 100644 index c7fff55..0000000 --- a/docs/index.html +++ /dev/null @@ -1,112 +0,0 @@ -<!DOCTYPE html> - -<!-- - ~ Copyright (C) 2021 The Android Open Source Project - ~ - ~ 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. - --> - -<html> -<head> - <script src="https://unpkg.com/showdown@1/dist/showdown.min.js"></script> - <script> - function showMarkdownFile(responseText, file) { - const headerLevelStart = 1; - - var converter = new showdown.Converter(); - converter.setOption("customizedHeaderId", true); - converter.setOption("ghCompatibleHeaderId", true); - converter.setOption("headerLevelStart", headerLevelStart); - converter.setOption("tables", true); - - var divFile = document.getElementById("div-file").cloneNode(true); - divFile.getElementsByClassName("div-file-contents")[0].innerHTML = converter.makeHtml(responseText); - - // Show file name - divFile.getElementsByClassName("headline-file-name")[0].id = file - divFile.getElementsByClassName("headline-file-name")[0].innerText = file; - - // Generate table of contents - var toc = document.getElementById("div-toc-contents") - - // Add link to title - var titleClone = document.getElementById("div-sample-toc-title").cloneNode(true) - var titleLink = titleClone.getElementsByTagName("a")[0] - titleLink.href = "#" + file - titleLink.innerText = file - toc.appendChild(titleClone) - - var h2Elements = divFile.getElementsByClassName("div-file-contents")[0].getElementsByTagName("h" + headerLevelStart) - var sampleTocItem = document.getElementById("div-sample-toc-item") - for (let i = 0; i < h2Elements.length; i++) { - var clone = sampleTocItem.cloneNode(true) - var link = clone.getElementsByTagName("a")[0]; - link.href = "#" + h2Elements[i].id - link.innerText = h2Elements[i].innerText - toc.appendChild(clone) - } - toc.appendChild(document.getElementById("div-sample-toc-break").cloneNode(true)) - - divFile.hidden = false; - document.body.appendChild(divFile) - } - - document.addEventListener("DOMContentLoaded", function () { - resources = document.getElementsByClassName("embedded_resource"); - for (var i = 0; i < resources.length; i++) { - if (!resources[i].id.endsWith("-res")) { - continue; - } - if (resources[i].id === "default_file.html.frag-res") { - continue; - } - file = resources[i].id.substring(0, resources[i].id.length - "-res".length) - console.log(file, resources[i]) - showMarkdownFile(atob(resources[i].innerText), file) - } - - // Decode default_file - document.getElementById("default_file.html.frag-res").innerHTML = atob(document.getElementById("default_file.html.frag-res").innerText); - default_file = document.getElementById("default_file") - if (default_file) { - document.location.href = default_file.href - } - }); - </script> - <style> - #div-float-right { - position: fixed; - right: 0; - top: 0; - } - </style> -</head> -<body> -<div id="div-float-right"> - <h3 id="headline-toc">Table of contents</h3> - <div hidden> - <div id="div-sample-toc-title"><strong><a></a></strong></div> - <div id="div-sample-toc-item"><code><a></a></code></div> - <div id="div-sample-toc-break"><br /></div> - </div> - <div id="div-toc-contents"> - </div> -</div> -<div id="div-file" hidden> - <h2 class="headline-file-name"></h2> - <div class="div-file-contents"> - </div> -</div> -<!--RESOURCE_EMBED_HINT--> -</body> -</html> diff --git a/docs/insert_resource.py b/docs/insert_resource.py deleted file mode 100755 index 09c9ef1..0000000 --- a/docs/insert_resource.py +++ /dev/null @@ -1,41 +0,0 @@ -#!/usr/bin/env python3 - -import argparse -import base64 -import io -import os - -MAGIC = "<!--RESOURCE_EMBED_HINT-->\n" - - -def main(infile, outfile, resources): - """Embed resources into infile at the line `<!--RESOURCE_EMBED_HINT-->`.""" - inlines = infile.readlines() - magic = inlines.index(MAGIC) - - outlines = inlines[:magic] - for resource in resources: - resource_name, path = resource.rsplit(":", 1) - outlines.append('<div hidden class="embedded_resource" id="{}-res">\n'.format(os.path.basename(resource_name))) - with open(path, 'rb') as resource: - # Resources need to be base64 encoded. For example, the resource file may be in - # markdown format: - # `<name>` - # However, this is not valid HTML. So it cannot be embedded in the HTML file directly. - # The HTML renderer converts it to - # <code><name></code> - # This is valid HTML. See index.html. - outlines.append(base64.b64encode(resource.read()).decode()) - outlines.append('</div>\n') - outlines += inlines[magic:] - - outfile.writelines(outlines) - - -if __name__ == '__main__': - parser = argparse.ArgumentParser(description=main.__doc__) - parser.add_argument("--infile", required=True, type=argparse.FileType('r'), help="input file") - parser.add_argument("--outfile", required=True, type=argparse.FileType('w'), help="output file") - parser.add_argument("resources", metavar="NAME:PATH", nargs='+', help="resource files") - args = parser.parse_args() - main(**vars(args)) diff --git a/docs/templates/func.vm b/docs/templates/func.vm deleted file mode 100644 index 50aafe4..0000000 --- a/docs/templates/func.vm +++ /dev/null @@ -1,21 +0,0 @@ -#[[#]]# `${funcInfo.functionName}` - -<pre> -${util.funcSummary($funcInfo)} -</pre> - -${funcInfo.docString} - -#[[##]]# Parameters - -#if (!$funcInfo.getParameterList().isEmpty()) - -#foreach ($param in $funcInfo.getParameterList()) -<a name="${funcInfo.functionName}-${param.name}"/> **`${param.name}`** -#if(${param.mandatory}) *Required.* #else *Optional.* #end #if(!${param.getDefaultValue().isEmpty()}) *Default is* `${param.getDefaultValue()}`. #end ${param.docString} - -#end -#else -No parameters. - -#end diff --git a/docs/templates/provider.vm b/docs/templates/provider.vm deleted file mode 100644 index ed1804f..0000000 --- a/docs/templates/provider.vm +++ /dev/null @@ -1,20 +0,0 @@ -#[[#]]# `${providerName}` - -<pre> -${util.providerSummary($providerName, $providerInfo)} -</pre> - -${providerInfo.docString} - -#[[##]]# Fields - -#if (!$providerInfo.fieldInfoList.isEmpty()) - -#foreach ($field in $providerInfo.fieldInfoList) -<a name="${providerName}-${field.name}" /> **`${field.name}`** -${field.docString} - -#end -#else -No fields. -#end diff --git a/docs/templates/rule.vm b/docs/templates/rule.vm deleted file mode 100644 index 7ad7e93..0000000 --- a/docs/templates/rule.vm +++ /dev/null @@ -1,21 +0,0 @@ -#[[#]]# `${ruleName}` - -<pre> -${util.ruleSummary($ruleName, $ruleInfo)} -</pre> - -${ruleInfo.docString} - -#[[##]]# Attributes - -#if (!$ruleInfo.getAttributeList().isEmpty()) - -#foreach ($attribute in $ruleInfo.getAttributeList()) -<a name="${ruleName}-${attribute.name}" /> **`${attribute.name}`** -*${util.attributeTypeString($attribute)}.* #if(${attribute.mandatory}) *Required.* #else *Optional.* #end #if(!${attribute.defaultValue.isEmpty()}) *Default is* `${attribute.defaultValue}`. #end $attribute.docString - -#end -#else -No attributes. - -#end |