1# Copyright 2022 The Bazel Authors. All rights reserved. 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"""Generate the reference documentation. 15 16How to: 17 bazel build //doc_build:reference 18 cp bazel-bin/doc_build/reference.md docs/latest.md 19 git commit -m 'update docs' docs/latest.md 20""" 21 22load("@bazel_skylib//:bzl_library.bzl", "bzl_library") 23load("@stardoc//stardoc:stardoc.bzl", "stardoc") 24load("@rules_python//python:defs.bzl", "py_library") 25load("//:version.bzl", "version") 26 27package(default_package_metadata = ["//:license", "//:package_info"]) 28 29filegroup( 30 name = "standard_package", 31 srcs = [ 32 "BUILD", 33 ] + glob([ 34 "*.bzl", 35 "*.py", 36 ]), 37 visibility = ["//distro:__pkg__"], 38) 39 40exports_files( 41 glob([ 42 "*.bzl", 43 ]), 44 visibility = [ 45 "//distro:__pkg__", 46 ], 47) 48 49# pairs of rule name and the source file to get it from 50# Must put macro wrapped rules after their wrapper 51# buildifier: leave-alone, do not sort 52ORDER = [ 53 ("license", "//rules:license.bzl"), 54 ("_license", "//rules:license.bzl"), 55 ("license_kind", "//rules:license_kind.bzl"), 56 ("_license_kind", "//rules:license_kind.bzl"), 57 ("package_info", "//rules:package_info.bzl"), 58 ("_package_info", "//rules:package_info.bzl"), 59 ("LicenseInfo", "//rules:providers.bzl"), 60 ("LicenseKindInfo", "//rules:providers.bzl"), 61 ("PackageInfo", "//rules:providers.bzl"), 62 ("gather_metadata_info", "//rules_gathering:gather_metadata.bzl"), 63 ("gather_metadata_info_and_write", "//rules_gathering:gather_metadata.bzl"), 64 ("trace", "//rules_gathering:trace.bzl"), 65] 66 67genrule( 68 name = "reference", 69 srcs = ["%s.md" % rule for rule, _ in ORDER], 70 outs = ["reference.md"], 71 cmd = "$(location :merge) $(SRCS) >$@", 72 tools = [":merge"], 73) 74 75[ 76 stardoc( 77 name = "%s_gen" % rule, 78 out = "%s.md" % rule, 79 input = src, 80 symbol_names = [ 81 rule, 82 ], 83 deps = [":lib_of_everything"], 84 ) 85 for rule, src in ORDER 86 if src 87] 88 89# gather all rules that should be documented 90bzl_library( 91 name = "lib_of_everything", 92 srcs = [ 93 "//:version.bzl", 94 "//rules:standard_package", 95 "//rules_gathering:standard_package", 96 ], 97 visibility = ["//visibility:public"], 98) 99 100# This is experimental. We are waiting for stardoc to get the features which 101# are done in merge. 102py_binary( 103 name = "merge", 104 srcs = ["merge.py"], 105 python_version = "PY3", 106 srcs_version = "PY3", 107 visibility = ["//visibility:private"], 108) 109