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