blob: 0fea717898bd2d7d23f83c87d5ccd4d154492188 [file] [log] [blame]
# 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.
# 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".
# 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 will be inserted at the top
# of the 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 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.
# 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/$"
# 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")
"'reference_repo_path' must be defined for cpp_docgen")
"'library_name' must be defined for cpp_docgen")
clang_doc_zip = "$target_gen_dir/${target_name}"
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
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 = [
rebase_path(clang_doc_zip, root_build_dir),
rebase_path("//", root_build_dir),
".", # The current directory is the build dir when run from Ninja.
rebase_path(include_base, root_build_dir),
# Everything gets put inside the "reference" folder so add that when generating the
# absolute "TOC" path for devsite.
if (defined(invoker.overview)) {
args += [
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 (""),
# plus the "" and "_toc.yaml" files.
outputs = process_file_template(
[ "${invoker.out_dir}/{{source_file_part}}.md" ])
outputs += [
args += [
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 += [
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
# 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" ])