| # 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" ]) |
| } |
| } |