xref: /aosp_15_r20/external/pigweed/pw_docgen/py/pw_docgen/seed.py (revision 61c4878ac05f98d0ceed94b57d316916de578985)
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