You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
127 lines
3.9 KiB
127 lines
3.9 KiB
# 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.
|
|
# other_deps: Dependencies on any other types of targets.
|
|
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
|
|
}
|
|
if (defined(invoker.other_deps)) {
|
|
_all_deps += invoker.other_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) {
|
|
}
|
|
}
|
|
}
|