• 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_docs_google_analytics_id = ""
26}
27
28# Defines a group of documentation files and assets.
29#
30# Args:
31#   sources: Source files for the documentation (.rst or .md).
32#   inputs: Additional resource files for the docs, such as images.
33#   group_deps: Other pw_doc_group targets on which this group depends.
34#   report_deps: Report card targets on which documentation depends.
35#   other_deps: Dependencies on any other types of targets.
36template("pw_doc_group") {
37  if (defined(invoker.sources)) {
38    _sources = invoker.sources
39  } else {
40    _sources = []
41  }
42
43  if (defined(invoker.inputs)) {
44    _inputs = invoker.inputs
45  } else {
46    _inputs = []
47  }
48
49  assert(defined(invoker.sources) || defined(invoker.inputs),
50         "pw_doc_group requires at least one of sources or inputs")
51
52  _all_deps = []
53  if (defined(invoker.group_deps)) {
54    _all_deps += invoker.group_deps
55  }
56  if (defined(invoker.report_deps)) {
57    _all_deps += invoker.report_deps
58  }
59  if (defined(invoker.other_deps)) {
60    _all_deps += invoker.other_deps
61  }
62
63  # Create a group containing the source and input files so that docs are
64  # rebuilt on file modifications.
65  pw_input_group(target_name) {
66    metadata = {
67      pw_doc_sources = rebase_path(_sources, root_build_dir)
68      pw_doc_inputs = rebase_path(_inputs, root_build_dir)
69    }
70    deps = _all_deps
71    inputs = _sources + _inputs
72  }
73}
74
75# Creates a target to build HTML documentation from groups of sources.
76#
77# Args:
78#   deps: List of pw_doc_group targets.
79#   sources: Top-level documentation .rst source files.
80#   conf: Configuration script (conf.py) for Sphinx.
81#   output_directory: Path to directory to which HTML output is rendered.
82template("pw_doc_gen") {
83  assert(defined(invoker.deps),
84         "pw_doc_gen requires doc groups as dependencies")
85  assert(defined(invoker.sources) && invoker.sources != [],
86         "pw_doc_gen requires a 'sources' list with at least one .rst source")
87  assert(defined(invoker.conf),
88         "pw_doc_gen requires a 'conf' argument pointing a top-level conf.py")
89  assert(defined(invoker.output_directory),
90         "pw_doc_gen requires an 'output_directory' argument")
91
92  # Collects all dependency metadata into a single JSON file.
93  _metadata_file_target = "${target_name}_metadata"
94  generated_file(_metadata_file_target) {
95    outputs = [ "$target_gen_dir/$target_name.json" ]
96    data_keys = [
97      "pw_doc_sources",
98      "pw_doc_inputs",
99    ]
100    output_conversion = "json"
101    deps = invoker.deps
102  }
103
104  _script_args = [
105    "--gn-root",
106    rebase_path("//", root_build_dir),
107    "--gn-gen-root",
108    rebase_path(root_gen_dir, root_build_dir) + "/",
109    "--sphinx-build-dir",
110    rebase_path("$target_gen_dir/pw_docgen_tree", root_build_dir),
111    "--conf",
112    rebase_path(invoker.conf, root_build_dir),
113    "--out-dir",
114    rebase_path(invoker.output_directory, root_build_dir),
115  ]
116
117  # Enable Google Analytics if a measurement ID is provided
118  if (pw_docs_google_analytics_id != "") {
119    _script_args += [
120      "--google-analytics-id",
121      pw_docs_google_analytics_id,
122    ]
123  }
124
125  # Metadata JSON file path.
126  _script_args += [ "--metadata" ]
127  _script_args +=
128      rebase_path(get_target_outputs(":$_metadata_file_target"), root_build_dir)
129
130  _script_args += rebase_path(invoker.sources, root_build_dir)
131
132  # Required to set the PYTHONPATH for any automodule/class/function RST
133  # directives.
134  _python_metadata_deps = [ "$dir_pw_docgen/py" ]
135  if (defined(invoker.python_metadata_deps)) {
136    _python_metadata_deps += invoker.python_metadata_deps
137  }
138
139  if (pw_docgen_BUILD_DOCS) {
140    pw_python_action(target_name) {
141      script = "$dir_pw_docgen/py/pw_docgen/docgen.py"
142      args = _script_args
143      deps = [ ":$_metadata_file_target" ]
144      python_metadata_deps = _python_metadata_deps
145      inputs = [ invoker.conf ]
146      inputs += invoker.sources
147      stamp = true
148    }
149  } else {
150    group(target_name) {
151    }
152  }
153}
154