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"""Generates additional documentation for SEEDs.""" 15 16import argparse 17import json 18from pathlib import Path 19 20 21def _parse_args() -> argparse.Namespace: 22 """Parses command-line arguments.""" 23 24 parser = argparse.ArgumentParser(description=__doc__) 25 parser.add_argument( 26 '--output', 27 type=Path, 28 required=True, 29 help='Output file to write', 30 ) 31 parser.add_argument( 32 'seed_metadata', 33 nargs='+', 34 help='JSON file containing information about a SEED', 35 ) 36 37 return parser.parse_args() 38 39 40_STATUS_BADGES = { 41 'draft': 'bdg-primary-line', 42 'open for comments': 'bdg-primary', 43 'last call': 'bdg-warning', 44 'accepted': 'bdg-success', 45 'rejected': 'bdg-danger', 46 'deprecated': 'bdg-secondary', 47 'superseded': 'bdg-info', 48 'on hold': 'bdg-secondary-line', 49 'meta': 'bdg-success-line', 50} 51 52 53def _status_badge(status: str) -> str: 54 badge = _STATUS_BADGES.get(status.lower().strip(), 'bdg-primary') 55 return f':{badge}:`{status}`' 56 57 58def _main(): 59 args = _parse_args() 60 61 # Table containing entries for each SEED. 62 seed_table = [ 63 '\n.. list-table::', 64 ' :widths: auto', 65 ' :header-rows: 1\n', 66 ' * - Number', 67 ' - Title', 68 ' - Status', 69 ' - Author', 70 ' - Facilitator', 71 ] 72 73 # RST toctree including each SEED's source file. 74 seed_toctree = [] 75 76 for metadata_file in args.seed_metadata: 77 contents = Path(metadata_file).read_text(encoding='utf-8') 78 meta = json.loads(contents) 79 80 if 'changelist' in meta: 81 # The SEED has not yet been merged and points to an active CL. 82 change_link = ( 83 'https://pigweed-review.googlesource.com' 84 f'/c/pigweed/pigweed/+/{meta["changelist"]}' 85 ) 86 title = f'`{meta["title"]} <{change_link}>`__' 87 seed_toctree.append( 88 f'{meta["number"]}: {meta["title"]}<{change_link}>', 89 ) 90 else: 91 # The SEED document is in the source tree. 92 title = f':ref:`{meta["title"]} <seed-{meta["number"]}>`' 93 seed_toctree.append(Path(meta["rst_file"]).stem) 94 95 facilitator = meta.get('facilitator', 'Unassigned') 96 97 seed_table.extend( 98 [ 99 f' * - {meta["number"]}', 100 f' - {title}', 101 f' - {_status_badge(meta["status"])}', 102 f' - {meta["author"]}', 103 f' - {facilitator}', 104 ] 105 ) 106 107 table = '\n'.join(seed_table) 108 109 # Hide the toctree it is only used for the sidebar. 110 toctree_lines = '\n '.join(seed_toctree) 111 112 # fmt: off 113 toctree = ( 114 '.. toctree::\n' 115 ' :hidden:\n' 116 '\n ' 117 f'{toctree_lines}' 118 ) 119 # fmt: on 120 121 args.output.write_text(f'{table}\n\n{toctree}', encoding='utf-8') 122 123 124if __name__ == '__main__': 125 _main() 126