1# Copyright 2023 The Pigweed Authors 2# 3# Licensed under the Apache License, Version 2.0 (the "License"); you may not 4# use this file except in compliance with the License. You may obtain a copy of 5# the License at 6# 7# https://www.apache.org/licenses/LICENSE-2.0 8# 9# Unless required by applicable law or agreed to in writing, software 10# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 11# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the 12# License for the specific language governing permissions and limitations under 13# the License. 14 15import("//build_overrides/pigweed.gni") 16 17import("$dir_pw_build/python.gni") 18import("$dir_pw_docgen/docs.gni") 19 20# Defines a directory of SEED proposals, generating an RST snippet containing 21# information about each of them. 22# 23# Args: 24# index_file: Base .rst file in which the index will be defined. 25# seeds: Nonempty list of `pw_seed` targets defining the SEEDs to include in 26# the index. All targets must previously have been defined in the same 27# BUILD.gn file. 28# 29template("pw_seed_index") { 30 assert(defined(invoker.index_file), "Must provide an index file") 31 assert(defined(invoker.seeds) && invoker.seeds != [], 32 "A SEED index must contain SEEDs") 33 34 _gen_target = "${target_name}.gen" 35 _index_rst_output = "$target_gen_dir/${target_name}" 36 37 _script_args = [ 38 "--output", 39 rebase_path(_index_rst_output, root_build_dir), 40 ] 41 42 foreach(_seed_target, invoker.seeds) { 43 _outputs = [] 44 _outputs = get_target_outputs("${_seed_target}.metadata") 45 _script_args += [ rebase_path(_outputs[0], root_build_dir) ] 46 } 47 48 pw_python_action(_gen_target) { 49 script = "$dir_pw_docgen/py/pw_docgen/seed.py" 50 args = _script_args 51 outputs = [ _index_rst_output ] 52 deps = invoker.seeds 53 } 54 55 pw_doc_group(target_name) { 56 sources = [ invoker.index_file ] 57 inputs = [ _index_rst_output ] 58 group_deps = invoker.seeds 59 other_deps = [ ":$_gen_target" ] 60 } 61} 62 63# Defines a SEED document suitable for inclusion in a SEED directory. 64# The `target_name` of the SEED target should be its 4-digit number and nothing 65# else. 66# 67# Args: 68# 69# sources (optional): If the SEED docs are already in-tree, list of the RST 70# source files. 71# 72# inputs (optional): If the SEED docs are already in-tree, list of any 73# additional resource files the docs require (images, graphs, etc.). 74# 75# changelist (optional): If the SEED has not yet been merged, the number of the 76# CL on Gerrit where the SEED is being reviewed. 77# 78# title (required): The title of the SEED. 79# 80# authors (required): Comma-separated list of SEED authors. 81# 82# facilitator (optional): Pigweed team member facilitating the SEED. 83# 84# status (required): Status of the SEED. One of: 85# Draft, Open for Comments, Last Call, Accepted, Rejected, On Hold, 86# Deprecated, Superseded, Meta 87# 88# A SEED target must set either `sources` or `changelist` to be valid. 89template("pw_seed") { 90 _has_sources = defined(invoker.sources) && invoker.sources != [] 91 assert(_has_sources || defined(invoker.changelist), 92 "A SEED must either have in-tree sources or an active CL") 93 assert(defined(invoker.title), "SEEDs must have a title") 94 assert(defined(invoker.status), "SEEDs must list their status") 95 assert(defined(invoker.author), "SEEDs must list their author(s)") 96 97 _metadata_file = "${target_gen_dir}/${target_name}.metadata.json" 98 _metadata_target = "${target_name}.metadata" 99 100 _metadata = { 101 number = target_name 102 title = invoker.title 103 status = invoker.status 104 author = invoker.author 105 106 if (defined(invoker.facilitator)) { 107 facilitator = invoker.facilitator 108 } 109 } 110 111 if (_has_sources) { 112 _sources = invoker.sources 113 _metadata.rst_file = _sources[0] 114 } else { 115 _metadata.changelist = invoker.changelist 116 } 117 118 generated_file(_metadata_target) { 119 contents = _metadata 120 output_conversion = "json" 121 outputs = [ _metadata_file ] 122 } 123 124 if (_has_sources) { 125 pw_doc_group(target_name) { 126 other_deps = [ ":${_metadata_target}" ] 127 forward_variables_from(invoker, 128 [ 129 "sources", 130 "inputs", 131 ]) 132 } 133 } else { 134 group(target_name) { 135 deps = [ ":${_metadata_target}" ] 136 not_needed(invoker, [ "*" ]) 137 } 138 } 139} 140