1# Copyright (C) 2021 The Android Open Source Project 2# 3# Licensed under the Apache License, Version 2.0 (the "License"); 4# you may not use this file except in compliance with the License. 5# You may obtain a copy of the License at 6# 7# http://www.apache.org/licenses/LICENSE-2.0 8# 9# Unless required by applicable law or agreed to in writing, software 10# distributed under the License is distributed on an "AS IS" BASIS, 11# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12# See the License for the specific language governing permissions and 13# limitations under the License. 14 15load("//build/bazel_common_rules/dist:dist.bzl", "copy_to_dist_dir") 16load("@io_bazel_stardoc//stardoc:stardoc.bzl", "stardoc") 17load("@bazel_skylib//:bzl_library.bzl", "bzl_library") 18 19# TODO: Add aspect_template when necessary 20def docs( 21 name, 22 srcs, 23 default = None, 24 deps = None, 25 func_template = None, 26 provider_template = None, 27 rule_template = None): 28 """Build docs. 29 30 The following rules are also generated: 31 - `{name}_dist` is created for distribution 32 - `{name}_server` is created for seeing docs locally. View with 33 ``` 34 bazel run {name}_server 35 ``` 36 37 Args: 38 name: name of this rule. 39 srcs: sources (`*.bzl` files) to generate docs. Docs for definitions in 40 these files are emitted. 41 42 `srcs` must be a list of real files. Labels to rules are not accepted. 43 default: An element in `srcs` that's shown in the renderer by default. 44 deps: additional dependencies of `srcs`. Definitions in these files do 45 not show up in the final output. 46 func_template: Template for generating docs for functions. 47 provider_template: Template for generating docs for providers. 48 rule_template: Template for generating docs for rules. 49 """ 50 51 all_deps = [] 52 all_deps += srcs 53 if deps != None: 54 all_deps += deps 55 56 if func_template == None: 57 func_template = "//build/bazel_common_rules/docs:templates/func.vm" 58 if provider_template == None: 59 provider_template = "//build/bazel_common_rules/docs:templates/provider.vm" 60 if rule_template == None: 61 rule_template = "//build/bazel_common_rules/docs:templates/rule.vm" 62 63 bzl_library( 64 name = name + "_deps", 65 srcs = all_deps, 66 ) 67 68 all_markdown_files = [] 69 for src in srcs: 70 stardoc( 71 name = name + "-" + src, 72 out = name + "/" + src, 73 input = src, 74 deps = [":" + name + "_deps"], 75 func_template = func_template, 76 provider_template = provider_template, 77 rule_template = rule_template, 78 ) 79 all_markdown_files.append((name + "/" + src, src)) 80 81 native.filegroup( 82 name = name + "_markdown_files", 83 srcs = [target for target, _ in all_markdown_files], 84 ) 85 86 default_file_cmd = """touch $@ && """ 87 for target, src in all_markdown_files: 88 if default == src: 89 default_file_cmd += """echo '<div hidden><a href="#{src}" id="default_file">{src}</a></div>' >> $@ &&""".format( 90 src = src, 91 ) 92 break 93 default_file_cmd += ":" 94 95 native.genrule( 96 name = name + "_default_file.html.frag", 97 srcs = [ 98 ], 99 outs = [ 100 name + "/docs_resources/default_file.html.frag", 101 ], 102 cmd = default_file_cmd, 103 ) 104 105 native.genrule( 106 name = name, 107 srcs = [ 108 "//build/bazel_common_rules/docs:index.html", 109 ":{name}_default_file.html.frag".format(name = name), 110 ":{name}_markdown_files".format(name = name), 111 ], 112 outs = [ 113 name + "/root/index.html", 114 ], 115 cmd = """ 116 $(location //build/bazel_common_rules/docs:insert_resource.py) \ 117 --infile $(location //build/bazel_common_rules/docs:index.html) \ 118 --outfile $(location {name}/root/index.html) \ 119 $(location :{name}_default_file.html.frag) \ 120 $(locations :{name}_markdown_files) 121 """.format(name = name), 122 tools = [ 123 "//build/bazel_common_rules/docs:insert_resource.py", 124 ], 125 ) 126 127 native.genrule( 128 name = name + "_run_server.sh", 129 srcs = [], 130 outs = [ 131 name + "/run_server.sh", 132 ], 133 cmd = """ 134 cat > $(location {name}/run_server.sh) <<< '#!/usr/bin/env sh 135cd $$(dirname $$0)/{name}/root && 136python3 -m http.server 8080 137' 138 chmod +x $(location {name}/run_server.sh) 139 """.format(name = name), 140 ) 141 142 native.sh_binary( 143 name = name + "_server", 144 srcs = [ 145 ":{name}_run_server.sh".format(name = name), 146 ], 147 data = [":" + name], 148 ) 149 150 copy_to_dist_dir( 151 name = name + "_dist", 152 data = [":" + name], 153 ) 154