| # 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("$dir_pw_build/input_group.gni") |
| 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 |
| } |
| |
| # 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_out_dir), |
| "--gn-gen-root", |
| rebase_path(root_gen_dir, root_out_dir) + "/", |
| "--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"), |
| "--metadata", |
| ] |
| |
| # Metadata JSON file path. |
| _script_args += |
| get_path_info(get_target_outputs(":$_metadata_file_target"), "abspath") |
| |
| foreach(path, invoker.sources) { |
| _script_args += [ get_path_info(path, "abspath") ] |
| } |
| |
| # TODO(frolv): Have a way of indicating that a toolchain should build docs. |
| if (current_toolchain == default_toolchain) { |
| pw_python_script(target_name) { |
| script = "$dir_pw_docgen/py/docgen.py" |
| args = _script_args |
| deps = [ ":$_metadata_file_target" ] |
| inputs = [ invoker.conf ] |
| inputs += invoker.sources |
| stamp = true |
| } |
| } else { |
| group(target_name) { |
| } |
| } |
| } |