2019-11-13 00:20:51 +00:00
|
|
|
# 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.
|
|
|
|
|
2019-12-13 21:11:32 +00:00
|
|
|
import("$dir_pw_build/input_group.gni")
|
2019-11-13 00:20:51 +00:00
|
|
|
import("$dir_pw_build/python_script.gni")
|
|
|
|
|
|
|
|
# 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
|
|
|
|
}
|
|
|
|
|
2019-12-13 21:11:32 +00:00
|
|
|
# Create a group containing the source and input files so that docs are
|
|
|
|
# rebuilt on file modifications.
|
|
|
|
pw_input_group(target_name) {
|
2019-11-13 00:20:51 +00:00
|
|
|
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.
|
2019-11-25 21:56:31 +00:00
|
|
|
# sources: Top-level documentation .rst source files.
|
2019-11-13 00:20:51 +00:00
|
|
|
# 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")
|
2019-11-25 21:56:31 +00:00
|
|
|
assert(defined(invoker.sources) && invoker.sources != [],
|
|
|
|
"pw_doc_gen requires a 'sources' list with at least one .rst source")
|
2019-11-13 00:20:51 +00:00
|
|
|
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",
|
2019-11-25 21:56:31 +00:00
|
|
|
rebase_path("//", root_out_dir),
|
|
|
|
"--gn-gen-root",
|
|
|
|
rebase_path(root_gen_dir, root_out_dir) + "/",
|
2019-11-13 00:20:51 +00:00
|
|
|
"--sphinx-build-dir",
|
|
|
|
get_path_info("$target_gen_dir/pw_docgen_tree", "abspath"),
|
|
|
|
"--conf",
|
|
|
|
get_path_info(invoker.conf, "abspath"),
|
|
|
|
"--out-dir",
|
|
|
|
get_path_info(invoker.output_directory, "abspath"),
|
2019-11-25 21:56:31 +00:00
|
|
|
"--metadata",
|
2019-11-13 00:20:51 +00:00
|
|
|
]
|
|
|
|
|
|
|
|
# Metadata JSON file path.
|
|
|
|
_script_args +=
|
|
|
|
get_path_info(get_target_outputs(":$_metadata_file_target"), "abspath")
|
|
|
|
|
2019-11-25 21:56:31 +00:00
|
|
|
foreach(path, invoker.sources) {
|
|
|
|
_script_args += [ get_path_info(path, "abspath") ]
|
|
|
|
}
|
|
|
|
|
2019-11-13 00:20:51 +00:00
|
|
|
pw_python_script(target_name) {
|
|
|
|
script = "$dir_pw_docgen/py/docgen.py"
|
|
|
|
args = _script_args
|
|
|
|
deps = [
|
|
|
|
":$_metadata_file_target",
|
|
|
|
]
|
|
|
|
inputs = [
|
2019-11-15 01:22:08 +00:00
|
|
|
invoker.conf,
|
2019-11-13 00:20:51 +00:00
|
|
|
]
|
2019-11-25 21:56:31 +00:00
|
|
|
inputs += invoker.sources
|
2019-11-13 00:20:51 +00:00
|
|
|
stamp = true
|
|
|
|
}
|
|
|
|
}
|