| # Copyright 2024 The Fuchsia Authors. All rights reserved. |
| # Use of this source code is governed by a BSD-style license that can be |
| # found in the LICENSE file. |
| |
| import("//build/bazel/bazel_build_action.gni") |
| import("//build/compiled_action.gni") |
| |
| # Provides a mechanism for creating a zip file containing all of the |
| # documentation defined in the bazel build rules. |
| # |
| # Args: |
| # textproto_targets: (required) |
| # The set of targets that generate the text protos. |
| # This target should be an `extract_bazel_doc_textproto()` target. |
| # Type: list of strings (GN labels) |
| # |
| # docset_name: (required) |
| # The name of the docset to generate. |
| # |
| # reference_repo_path: (required) |
| # The path to copy these documents when built in infrastructure. |
| # |
| # docsite_base_path: (required) |
| # The base path for all docs on the docsite. eg. reference/bazel_sdk |
| # |
| # output_name: (optional) |
| # The name of the zip file to create. This file will be created relative to |
| # the target_gen_dir. |
| # Default: docs.zip |
| # Type: String |
| # |
| # deps: |
| # testonly: |
| # visibility: |
| # Usual GN meaning. |
| template("bazel_docgen") { |
| assert(defined(invoker.textproto_targets), |
| "textproto_targets must be defined") |
| assert(defined(invoker.docset_name), "docset_name must be defined") |
| assert(defined(invoker.reference_repo_path), |
| "reference_repo_path must be defined") |
| assert(defined(invoker.docsite_base_path), |
| "docsite_base_path must be defined") |
| |
| compiled_action(target_name) { |
| tool = "//tools/bazel-docgen:bin" |
| tool_output_name = "bazel-docgen" |
| |
| forward_variables_from(invoker, |
| [ |
| "testonly", |
| "visibility", |
| ]) |
| |
| proto_args = [] |
| |
| foreach(target, invoker.textproto_targets) { |
| gen_dir = get_label_info(target, "target_out_dir") |
| file_name = get_label_info(target, "name") + ".docs.textproto" |
| proto = rebase_path(gen_dir + "/" + file_name, root_build_dir) |
| |
| proto_args += [ |
| "--proto", |
| proto, |
| ] |
| } |
| |
| zip_file = "docs.zip" |
| if (defined(invoker.output_name)) { |
| zip_file = invoker.output_name |
| } |
| out_zip = "${target_gen_dir}/${zip_file}" |
| |
| args = proto_args + [ |
| "--zip_file", |
| rebase_path(out_zip, root_build_dir), |
| "--base_path", |
| invoker.docsite_base_path, |
| ] |
| |
| outputs = [ out_zip ] |
| |
| deps = invoker.textproto_targets |
| if (defined(invoker.deps)) { |
| deps += invoker.deps |
| } |
| |
| metadata = { |
| # Record metadata for the //tools/docsgen build API. |
| generated_docset = [ |
| { |
| name = invoker.docset_name |
| archive = { |
| origin_file = rebase_path(out_zip, root_build_dir) |
| } |
| dest_folder = invoker.reference_repo_path |
| }, |
| ] |
| } |
| } |
| } |
| |
| # Wraps a `starlark_doc_extract()` in a `BUILD.bazel` file. |
| # Use this template to create a textproto from the given target. |
| # |
| # Args: |
| # bazel_target: (required) |
| # Bazel target to wrap. |
| # This target should be a `starlark_doc_extract()` target and should not |
| # include the textproto ending. |
| # |
| # deps: |
| # testonly: |
| # visibility: |
| # Usual GN meaning. |
| template("extract_bazel_doc_textproto") { |
| assert(defined(invoker.bazel_target), "bazel_target must be defined") |
| |
| bazel_build_action(target_name) { |
| forward_variables_from(invoker, |
| [ |
| "deps", |
| "metadata", |
| "testonly", |
| "visibility", |
| ]) |
| bazel_target = invoker.bazel_target + ".textproto" |
| copy_outputs = [ |
| { |
| bazel = "{{BAZEL_TARGET_OUT_DIR}}/{{BAZEL_TARGET_NAME}}" |
| ninja = "${target_name}.docs.textproto" |
| }, |
| ] |
| } |
| } |