| # 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"), |
| ("trace", "//rules_gathering:trace.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", |
| "//rules_gathering:standard_package", |
| ], |
| 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"], |
| ) |