tools/cppdocgen/cpp_docgen.gni

# Copyright 2022 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/compiled_action.gni")
import("//tools/cppdocgen/clang_doc.gni")

# Generates markdown documentation from the public headers of a library.
#
# By convention, call the docgen target for a library "docs", giving a full
# label of the form "//sdk/lib/fdio:docs".
#
# PARAMETERS
#
#   headers [list of strings] (required)
#       Paths to the public headers you want to document.
#
#   overview [file name] (optional)
#       If set, the contents of this file (typically called README.md) will be inserted at the top
#       of the index.md output file. This would typically contain an overview of the library
#       functionality. This file's title will also provide the title for the output index.
#
#   library_name [string] (required)
#       User-visible library name (not a file name). This is used for titles to name the library.
#
#   include_dir [string] (optional)
#       The directory relative to which the consumers of this library will include its files.
#       Most code inside the Fuchsia tree includes files relative to the source root (this will be
#       the default of include_dir is unspecified, libraries in the SDK usually use a
#       library-specific location like an "include" subdirectory. This location is interpreted as
#       relative to the current directory (like the built-in include_dirs variable).
#
#   toc_path [string] (required)
#       The absolute path to where the output will be hosted on devsite. This is used for generating
#       the paths in _toc.yaml which must be absolute. This will be something like
#       "/docs/reference/libs/mylib"
#
#   reference_repo_path [string] (required)
#       The relative path in https://fuchsia.googlesource.com/reference-docs/ where the output will
#       be staged by the bots. Generally something like "sdk/lib/mylib". The output will appear
#       on the site in /reference/sdk/lib/mylib
#
#   deps, visibility
#       Normal meaning.
#
# ZIP FILE OUTPUT
#
#   out_zip [string] (optional for zip output)
#       Name of the zip file to generate with the generated markdown documentation. This will
#       default to "$target_out_dir/$library_name.zip"
#
# RAW .md FILE OUTPUT (for manual testing only)
#
#   out_dir [string] (required for directory-based output)
#       The name of the directory to put the output files in. Currently the build assumes the output
#       files that will be generated based on the input header names. This is used for testing the
#       tool with known golden files. Normal documentation output should use zip file output as
#       input into the doc serving pipeline.

template("cpp_docgen") {
  assert(defined(invoker.headers), "'headers' must be defined for cpp_docgen")
  assert(defined(invoker.reference_repo_path),
         "'reference_repo_path' must be defined for cpp_docgen")
  assert(defined(invoker.library_name),
         "'library_name' must be defined for cpp_docgen")
  clang_doc_zip = "$target_gen_dir/${target_name}_clang_doc.zip"

  final_target_name = target_name
  clang_doc_target_name = "${target_name}_clang_doc"

  clang_doc_headers(clang_doc_target_name) {
    out_zip = clang_doc_zip
    forward_variables_from(invoker,
                           [
                             "deps",
                             "headers",
                           ])
    visibility = [ ":$final_target_name" ]
  }

  if (defined(invoker.include_dir)) {
    include_base = invoker.include_dir
  } else {
    include_base = "//"  # Default to the source root if unspecified.
  }

  compiled_action(target_name) {
    tool = "//tools/cppdocgen"

    # Even if the .zip file hasn't changed, we want to rebuild if any of the public headers have
    # since there could be #defines that are updated that aren't captured by clang-doc output.
    inputs = [ clang_doc_zip ] + invoker.headers

    args = [
      "--in-zip",
      rebase_path(clang_doc_zip, root_build_dir),
      "--lib-name",
      invoker.library_name,
      "--source-root",
      rebase_path("//", root_build_dir),
      "--build-dir",
      ".",  # The current directory is the build dir when run from Ninja.
      "--include-dir",
      rebase_path(include_base, root_build_dir),
      "--source-url",
      "https://fuchsia.googlesource.com/fuchsia/+/refs/heads/main/",

      # Everything gets put inside the "reference" folder so add that when generating the
      # absolute "TOC" path for devsite.
      "--toc-path",
      "/reference/${invoker.reference_repo_path}",
    ]

    if (defined(invoker.overview)) {
      args += [
        "--overview",
        rebase_path(invoker.overview, root_build_dir),
      ]
    }

    if (defined(invoker.out_dir)) {
      # Expect .md files in the output directory with the names of each header ("header.h.md"),
      # plus the "index.md" and "_toc.yaml" files.
      outputs = process_file_template(
              invoker.headers,
              [ "${invoker.out_dir}/{{source_file_part}}.md" ])
      outputs += [
        "${invoker.out_dir}/index.md",
        "${invoker.out_dir}/_toc.yaml",
      ]
      args += [
        "--out-dir",
        rebase_path(invoker.out_dir, root_build_dir),
      ]
    } else {
      # Normal zip file output.
      if (defined(invoker.out_zip)) {
        out_zip = invoker.out_zip
      } else {
        # Default zip file output name.
        out_zip = "$target_out_dir/${invoker.library_name}.zip"
      }

      outputs = [ out_zip ]
      args += [
        "--out-zip",
        rebase_path(out_zip, root_build_dir),
      ]

      metadata = {
        # Record metadata for the //tools/docsgen build API. This is available only for zip output.
        generated_docset = [
          {
            # This name is mostly just used for the commit messages for automated commits.
            name = invoker.library_name

            archive = {
              origin_file = rebase_path(out_zip, root_build_dir)
            }

            # This is the folder inside of the
            #   https://fuchsia.googlesource.com/reference-docs/
            # repo where the output will be automatically copied by the bots.
            dest_folder = invoker.reference_repo_path
          },
        ]
      }
    }

    args += rebase_path(invoker.headers, root_build_dir)

    deps = [ ":$clang_doc_target_name" ]
    forward_variables_from(invoker, [ "visibility" ])
  }
}