third_party/pigweed/repo/pw_docgen/docs.gni

   1 # Copyright 2019 The Pigweed Authors
   2 #
   3 # Licensed under the Apache License, Version 2.0 (the "License"); you may not
   4 # use this file except in compliance with the License. You may obtain a copy of
   5 # the License at
   6 #
   7 #     https://www.apache.org/licenses/LICENSE-2.0
   8 #
   9 # Unless required by applicable law or agreed to in writing, software
  10 # distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
  11 # WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
  12 # License for the specific language governing permissions and limitations under
  13 # the License.
  14
  15 import("//build_overrides/pigweed.gni")
  16
  17 import("$dir_pw_build/input_group.gni")
  18 import("$dir_pw_build/python_action.gni")
  19
  20 declare_args() {
  21   # Whether or not the current target should build docs.
  22   pw_docgen_BUILD_DOCS = false
  23 }
  24
  25 # Defines a group of documentation files and assets.
  26 #
  27 # Args:
  28 #   sources: Source files for the documentation (.rst or .md).
  29 #   inputs: Additional resource files for the docs, such as images.
  30 #   group_deps: Other pw_doc_group targets on which this group depends.
  31 #   report_deps: Report card targets on which documentation depends.
  32 template("pw_doc_group") {
  33   assert(defined(invoker.sources), "pw_doc_group requires a list of sources")
  34
  35   if (defined(invoker.inputs)) {
  36     _inputs = invoker.inputs
  37   } else {
  38     _inputs = []
  39   }
  40
  41   _all_deps = []
  42   if (defined(invoker.group_deps)) {
  43     _all_deps += invoker.group_deps
  44   }
  45   if (defined(invoker.report_deps)) {
  46     _all_deps += invoker.report_deps
  47   }
  48
  49   # Create a group containing the source and input files so that docs are
  50   # rebuilt on file modifications.
  51   pw_input_group(target_name) {
  52     metadata = {
  53       pw_doc_sources = rebase_path(invoker.sources, root_build_dir)
  54       pw_doc_inputs = rebase_path(_inputs, root_build_dir)
  55     }
  56     deps = _all_deps
  57     inputs = invoker.sources + _inputs
  58   }
  59 }
  60
  61 # Creates a target to build HTML documentation from groups of sources.
  62 #
  63 # Args:
  64 #   deps: List of pw_doc_group targets.
  65 #   sources: Top-level documentation .rst source files.
  66 #   conf: Configuration script (conf.py) for Sphinx.
  67 #   output_directory: Path to directory to which HTML output is rendered.
  68 template("pw_doc_gen") {
  69   assert(defined(invoker.deps),
  70          "pw_doc_gen requires doc groups as dependencies")
  71   assert(defined(invoker.sources) && invoker.sources != [],
  72          "pw_doc_gen requires a 'sources' list with at least one .rst source")
  73   assert(defined(invoker.conf),
  74          "pw_doc_gen requires a 'conf' argument pointing a top-level conf.py")
  75   assert(defined(invoker.output_directory),
  76          "pw_doc_gen requires an 'output_directory' argument")
  77
  78   # Collects all dependency metadata into a single JSON file.
  79   _metadata_file_target = "${target_name}_metadata"
  80   generated_file(_metadata_file_target) {
  81     outputs = [ "$target_gen_dir/$target_name.json" ]
  82     data_keys = [
  83       "pw_doc_sources",
  84       "pw_doc_inputs",
  85     ]
  86     output_conversion = "json"
  87     deps = invoker.deps
  88   }
  89
  90   _script_args = [
  91     "--gn-root",
  92     rebase_path("//", root_build_dir),
  93     "--gn-gen-root",
  94     rebase_path(root_gen_dir, root_build_dir) + "/",
  95     "--sphinx-build-dir",
  96     rebase_path("$target_gen_dir/pw_docgen_tree"),
  97     "--conf",
  98     rebase_path(invoker.conf),
  99     "--out-dir",
 100     rebase_path(invoker.output_directory),
 101     "--metadata",
 102   ]
 103
 104   # Metadata JSON file path.
 105   _script_args += rebase_path(get_target_outputs(":$_metadata_file_target"))
 106
 107   _script_args += rebase_path(invoker.sources)
 108
 109   if (pw_docgen_BUILD_DOCS) {
 110     pw_python_action(target_name) {
 111       script = "$dir_pw_docgen/py/pw_docgen/docgen.py"
 112       args = _script_args
 113       deps = [ ":$_metadata_file_target" ]
 114       inputs = [ invoker.conf ]
 115       inputs += invoker.sources
 116       stamp = true
 117     }
 118   } else {
 119     group(target_name) {
 120     }
 121   }
 122 }