• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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
15import("//build_overrides/pigweed.gni")
16
17import("$dir_pw_build/input_group.gni")
18import("$dir_pw_build/python_action.gni")
19
20declare_args() {
21  # Whether or not the current target should build docs.
22  pw_docgen_BUILD_DOCS = false
23
24  # Set to enable Google Analytics tracking of generated docs.
25  pw_docgen_GOOGLE_ANALYTICS_ID = ""
26
27  # Set to define the number of parallel threads to use during the Sphinx build.
28  pw_docgen_THREADS = ""
29}
30
31# Defines a group of documentation files and assets.
32#
33# Args:
34#   sources: Source files for the documentation (.rst or .md).
35#   inputs: Additional resource files for the docs, such as images.
36#   group_deps: Other pw_doc_group targets on which this group depends.
37#   report_deps: Report card targets on which documentation depends.
38#   other_deps: Dependencies on any other types of targets.
39template("pw_doc_group") {
40  assert(defined(invoker.sources) || defined(invoker.inputs),
41         "pw_doc_group requires at least one of sources or inputs")
42
43  # Create a group containing the source and input files so that docs are
44  # rebuilt on file modifications.
45  pw_input_group(target_name) {
46    _sources = []
47    if (defined(invoker.sources)) {
48      _sources = invoker.sources
49    }
50
51    _inputs = []
52    if (defined(invoker.inputs)) {
53      _inputs = invoker.inputs
54    }
55
56    metadata = {
57      pw_doc_sources = rebase_path(_sources, root_build_dir)
58      pw_doc_inputs = rebase_path(_inputs, root_build_dir)
59    }
60
61    deps = []
62    if (defined(invoker.group_deps)) {
63      deps += invoker.group_deps
64    }
65    if (defined(invoker.report_deps)) {
66      deps += invoker.report_deps
67    }
68    if (defined(invoker.other_deps)) {
69      deps += invoker.other_deps
70    }
71
72    inputs = _sources + _inputs
73  }
74}
75
76# Creates a target to build HTML documentation from groups of sources.
77#
78# Args:
79#   deps: List of pw_doc_group targets.
80#   python_metadata_deps: Python-related dependencies that are only used as deps
81#                         for generating Python package metadata list, not the
82#                         overall documentation generation. This should rarely
83#                         be used by non-Pigweed code.
84#   sources: Top-level documentation .rst source files.
85#   conf: Configuration script (conf.py) for Sphinx.
86#   output_directory: Path to directory to which HTML output is rendered.
87template("pw_doc_gen") {
88  assert(defined(invoker.deps),
89         "pw_doc_gen requires doc groups as dependencies")
90  assert(defined(invoker.sources) && invoker.sources != [],
91         "pw_doc_gen requires a 'sources' list with at least one .rst source")
92  assert(defined(invoker.conf),
93         "pw_doc_gen requires a 'conf' argument pointing a top-level conf.py")
94  assert(defined(invoker.output_directory),
95         "pw_doc_gen requires an 'output_directory' argument")
96
97  if (pw_docgen_BUILD_DOCS) {
98    # Collects all dependency metadata into a single JSON file.
99    _metadata_file_target = "${target_name}_metadata"
100    generated_file(_metadata_file_target) {
101      outputs = [ "$target_gen_dir/$target_name.json" ]
102      data_keys = [
103        "pw_doc_sources",
104        "pw_doc_inputs",
105      ]
106      output_conversion = "json"
107      deps = invoker.deps
108    }
109
110    pw_python_action(target_name) {
111      module = "pw_docgen.docgen"
112      args = [
113        "--gn-root",
114        rebase_path("//", root_build_dir),
115        "--gn-gen-root",
116        rebase_path(root_gen_dir, root_build_dir) + "/",
117        "--sphinx-build-dir",
118        rebase_path("$target_gen_dir/pw_docgen_tree", root_build_dir),
119        "--conf",
120        rebase_path(invoker.conf, root_build_dir),
121        "--out-dir",
122        rebase_path(invoker.output_directory, root_build_dir),
123      ]
124
125      # Enable Google Analytics if a measurement ID is provided
126      if (pw_docgen_GOOGLE_ANALYTICS_ID != "") {
127        args += [
128          "--google-analytics-id",
129          pw_docgen_GOOGLE_ANALYTICS_ID,
130        ]
131      }
132
133      # Override the default number of threads for the Sphinx build.
134      if (pw_docgen_THREADS != "") {
135        args += [
136          "-j",
137          pw_docgen_THREADS,
138        ]
139      }
140
141      # Metadata JSON file path.
142      args += [ "--metadata" ] +
143              rebase_path(get_target_outputs(":$_metadata_file_target"),
144                          root_build_dir)
145
146      args += rebase_path(invoker.sources, root_build_dir)
147
148      python_deps = [ "$dir_pw_docgen/py" ]
149      deps = [ ":$_metadata_file_target" ]
150
151      # Required to set the PYTHONPATH for any automodule/class/function RST
152      # directives.
153      python_metadata_deps = [ "$dir_pw_docgen/py" ]
154      if (defined(invoker.python_metadata_deps)) {
155        python_metadata_deps += invoker.python_metadata_deps
156      }
157
158      inputs = [ invoker.conf ] + invoker.sources
159      stamp = true
160    }
161  } else {
162    group(target_name) {
163    }
164  }
165}
166