tools/bazel-docgen/bazel_docgen.gni

# 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_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_target = invoker.bazel_target

  bazel_action(target_name) {
    forward_variables_from(invoker,
                           [
                             "bazel_inputs",
                             "deps",
                             "metadata",
                             "testonly",
                             "visibility",
                           ])
    command = "build"
    bazel_targets = [ bazel_target + ".textproto" ]
    copy_outputs = [
      {
        bazel = "{{BAZEL_TARGET_OUT_DIR}}/{{BAZEL_TARGET_NAME}}"
        ninja = "${target_name}.docs.textproto"
      },
    ]
  }
}