| # Copyright 2023 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/python.gni") |
| import("$dir_pw_docgen/docs.gni") |
| |
| # Defines a directory of SEED proposals, generating an RST snippet containing |
| # information about each of them. |
| # |
| # Args: |
| # index_file: Base .rst file in which the index will be defined. |
| # seeds: Nonempty list of `pw_seed` targets defining the SEEDs to include in |
| # the index. All targets must previously have been defined in the same |
| # BUILD.gn file. |
| # |
| template("pw_seed_index") { |
| assert(defined(invoker.index_file), "Must provide an index file") |
| assert(defined(invoker.seeds) && invoker.seeds != [], |
| "A SEED index must contain SEEDs") |
| |
| _gen_target = "${target_name}.gen" |
| _index_rst_output = "$target_gen_dir/${target_name}" |
| |
| _script_args = [ |
| "--output", |
| rebase_path(_index_rst_output, root_build_dir), |
| ] |
| |
| foreach(_seed_target, invoker.seeds) { |
| _outputs = [] |
| _outputs = get_target_outputs("${_seed_target}.metadata") |
| _script_args += [ rebase_path(_outputs[0], root_build_dir) ] |
| } |
| |
| pw_python_action(_gen_target) { |
| script = "$dir_pw_docgen/py/pw_docgen/seed.py" |
| args = _script_args |
| outputs = [ _index_rst_output ] |
| deps = invoker.seeds |
| } |
| |
| pw_doc_group(target_name) { |
| sources = [ invoker.index_file ] |
| inputs = [ _index_rst_output ] |
| group_deps = invoker.seeds |
| other_deps = [ ":$_gen_target" ] |
| } |
| } |
| |
| # Defines a SEED document suitable for inclusion in a SEED directory. |
| # The `target_name` of the SEED target should be its 4-digit number and nothing |
| # else. |
| # |
| # Args: |
| # |
| # sources (optional): If the SEED docs are already in-tree, list of the RST |
| # source files. |
| # |
| # inputs (optional): If the SEED docs are already in-tree, list of any |
| # additional resource files the docs require (images, graphs, etc.). |
| # |
| # changelist (optional): If the SEED has not yet been merged, the number of the |
| # CL on Gerrit where the SEED is being reviewed. |
| # |
| # title (required): The title of the SEED. |
| # |
| # authors (required): Comma-separated list of SEED authors. |
| # |
| # facilitator (optional): Pigweed team member facilitating the SEED. |
| # |
| # status (required): Status of the SEED. One of: |
| # Draft, Open for Comments, Last Call, Accepted, Rejected, On Hold, |
| # Deprecated, Superseded, Meta |
| # |
| # A SEED target must set either `sources` or `changelist` to be valid. |
| template("pw_seed") { |
| _has_sources = defined(invoker.sources) && invoker.sources != [] |
| assert(_has_sources || defined(invoker.changelist), |
| "A SEED must either have in-tree sources or an active CL") |
| assert(defined(invoker.title), "SEEDs must have a title") |
| assert(defined(invoker.status), "SEEDs must list their status") |
| assert(defined(invoker.author), "SEEDs must list their author(s)") |
| |
| _metadata_file = "${target_gen_dir}/${target_name}.metadata.json" |
| _metadata_target = "${target_name}.metadata" |
| |
| _metadata = { |
| number = target_name |
| title = invoker.title |
| status = invoker.status |
| author = invoker.author |
| |
| if (defined(invoker.facilitator)) { |
| facilitator = invoker.facilitator |
| } |
| } |
| |
| if (_has_sources) { |
| _sources = invoker.sources |
| _metadata.rst_file = _sources[0] |
| } else { |
| _metadata.changelist = invoker.changelist |
| } |
| |
| generated_file(_metadata_target) { |
| contents = _metadata |
| output_conversion = "json" |
| outputs = [ _metadata_file ] |
| } |
| |
| if (_has_sources) { |
| pw_doc_group(target_name) { |
| other_deps = [ ":${_metadata_target}" ] |
| forward_variables_from(invoker, |
| [ |
| "sources", |
| "inputs", |
| ]) |
| } |
| } else { |
| group(target_name) { |
| deps = [ ":${_metadata_target}" ] |
| not_needed(invoker, [ "*" ]) |
| } |
| } |
| } |