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