Skip to content

Commit a40cea0

Browse files
Kayce BasquesCQ Bot Account
Kayce Basques
authored and
CQ Bot Account
committed
pw_docgen: Single-source the module metadata
This change reduces boilerplate in module docs, ensures that metadata is consistent across all of a module's docs pages, and paves the way for improvements to //docs/modules.rst. Bug: 292582625 Change-Id: Ib38ac37d553e9d4baa2796e1b0c53e9f619703fe Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/193333 Presubmit-Verified: CQ Bot Account <pigweed-scoped@luci-project-accounts.iam.gserviceaccount.com> Commit-Queue: Kayce Basques <kayce@google.com> Reviewed-by: Chad Norvell <chadnorvell@google.com>
1 parent 25731b1 commit a40cea0

File tree

83 files changed

+863
-221
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

83 files changed

+863
-221
lines changed

‎docs/contributing/module_docs.rst

+31
Original file line numberDiff line numberDiff line change
@@ -226,6 +226,37 @@ The following sections provide instructions on how to write each content type.
226226
:ref:`docs-contrib-moduledocs-multipage` they might be an entire page of
227227
content or a section within a page.
228228

229+
.. _docs-contrib-moduledocs-metadata:
230+
231+
Module metadata
232+
===============
233+
1. Add a ``pigweed-module`` directive right after the title in your
234+
``docs.rst``:
235+
236+
.. code-block::
237+
238+
==========
239+
pw_example
240+
==========
241+
.. pigweed-module::
242+
:name: pw_example
243+
244+
2. Add metadata for your module in ``//docs/module_metadata.json``.
245+
See ``//docs/module_metadata_schema.json`` for the schema
246+
definition.
247+
248+
3. Add a ``pigweed-module-subpage`` directive right after the title
249+
in each of your other docs pages (if your module has multiple docs
250+
pages):
251+
252+
.. code-block::
253+
254+
=============
255+
API reference
256+
=============
257+
.. pigweed-module-subpage::
258+
:name: pw_example
259+
229260
.. _docs-contrib-moduledocs-sales:
230261

231262
Sales pitch

‎docs/module_metadata.json

+213
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,213 @@
1+
{
2+
"pw_alignment": {
3+
"tagline": "Natural object alignment, guaranteed",
4+
"status": "stable",
5+
"languages": [
6+
"C++17"
7+
]
8+
},
9+
"pw_allocator": {
10+
"tagline": "Flexible, safe, and measurable memory allocation",
11+
"status": "unstable",
12+
"languages": [
13+
"C++17"
14+
],
15+
"size": "400 to 1800 bytes"
16+
},
17+
"pw_async2": {
18+
"tagline": "Cooperative async tasks for embedded",
19+
"status": "experimental",
20+
"languages": [
21+
"C++17"
22+
]
23+
},
24+
"pw_bluetooth_sapphire": {
25+
"tagline": "Battle-tested Bluetooth with rock-solid reliability",
26+
"status": "unstable",
27+
"size": "1.5 to 2 mB",
28+
"languages": [
29+
"C++17"
30+
]
31+
},
32+
"pw_boot": {
33+
"tagline": "Simplified booting for C++ targets",
34+
"status": "stable",
35+
"languages": [
36+
"C++17"
37+
]
38+
},
39+
"pw_build_android": {
40+
"tagline": "Utilities for using Pigweed in Android platform",
41+
"status": "unstable",
42+
"languages": [
43+
"C++20"
44+
]
45+
},
46+
"pw_console": {
47+
"tagline": "Multi-purpose pluggable interactive console for dev & manufacturing",
48+
"status": "stable",
49+
"size": "N/A (host) but works best with pw_rpc on-device",
50+
"languages": [
51+
"Python"
52+
]
53+
},
54+
"pw_digital_io_linux": {
55+
"tagline": "Digital I/O interface for Linux userspace",
56+
"status": "unstable",
57+
"languages": [
58+
"C++17"
59+
]
60+
},
61+
"pw_emu": {
62+
"tagline": "Flexible emulators frontend",
63+
"status": "experimental",
64+
"languages": [
65+
"Python",
66+
"CLI"
67+
]
68+
},
69+
"pw_env_setup_zephyr": {
70+
"tagline": "Zephyr utilities",
71+
"status": "experimental"
72+
},
73+
"pw_format": {
74+
"tagline": "String formatting",
75+
"status": "experimental",
76+
"languages": [
77+
"Rust"
78+
]
79+
},
80+
"pw_function": {
81+
"tagline": "Embedded-friendly std::function",
82+
"status": "stable",
83+
"languages": [
84+
"C++17"
85+
]
86+
},
87+
"pw_fuzzer": {
88+
"tagline": "Better C++ code through easier fuzzing",
89+
"status": "unstable",
90+
"languages": [
91+
"C++17",
92+
"C++20"
93+
]
94+
},
95+
"pw_grpc": {
96+
"tagline": "pw_rpc over gRPC",
97+
"status": "unstable",
98+
"languages": [
99+
"C++17",
100+
"C++20"
101+
]
102+
},
103+
"pw_hdlc": {
104+
"tagline": "Simple, robust, and efficient serial communication",
105+
"status": "stable",
106+
"size": "1400 to 2600 bytes",
107+
"languages": [
108+
"Python",
109+
"C++17",
110+
"TypeScript"
111+
]
112+
},
113+
"pw_json": {
114+
"tagline": "Simple, efficient C++ JSON serialization",
115+
"status": "stable",
116+
"languages": [
117+
"C++17"
118+
]
119+
},
120+
"pw_kvs": {
121+
"tagline": "Lightweight, persistent key-value store",
122+
"status": "stable",
123+
"size": "~12 kB",
124+
"languages": [
125+
"C++17"
126+
]
127+
},
128+
"pw_multibuf": {
129+
"tagline": "A buffer API optimized for zero-copy messaging",
130+
"status": "unstable",
131+
"languages": [
132+
"C++17"
133+
]
134+
},
135+
"pw_perf_test": {
136+
"tagline": "Micro-benchmarks that are easy to write and run",
137+
"status": "unstable",
138+
"languages": [
139+
"C++17"
140+
]
141+
},
142+
"pw_result": {
143+
"tagline": "Error propagation primitives: value-or-error",
144+
"status": "stable",
145+
"languages": [
146+
"C++17"
147+
]
148+
},
149+
"pw_software_update": {
150+
"tagline": "Secure software delivery",
151+
"status": "experimental",
152+
"languages": [
153+
"Python",
154+
"C++17"
155+
]
156+
},
157+
"pw_span": {
158+
"tagline": "std::span for C++17",
159+
"status": "stable",
160+
"languages": [
161+
"C++17",
162+
"C++20"
163+
]
164+
},
165+
"pw_status": {
166+
"tagline": "Exception-free error propagation for embedded",
167+
"status": "stable",
168+
"languages": [
169+
"C++17",
170+
"C",
171+
"Python",
172+
"Java",
173+
"TypeScript",
174+
"Rust"
175+
]
176+
},
177+
"pw_string": {
178+
"tagline": "Efficient, easy, and safe string manipulation",
179+
"status": "stable",
180+
"size": "500 to 1500 bytes",
181+
"languages": [
182+
"C++17"
183+
]
184+
},
185+
"pw_tokenizer": {
186+
"tagline": "Compress strings to shrink logs by +75%",
187+
"status": "stable",
188+
"size": "50% reduction in log size",
189+
"languages": [
190+
"C++",
191+
"C11",
192+
"Python",
193+
"Rust",
194+
"TypeScript",
195+
"Java"
196+
]
197+
},
198+
"pw_toolchain_bazel": {
199+
"tagline": "A modular toolkit for declaring C/C++ toolchains in Bazel",
200+
"status": "unstable",
201+
"languages": [
202+
"Starlark"
203+
]
204+
},
205+
"pw_unit_test": {
206+
"tagline": "GoogleTest for embedded",
207+
"status": "stable"
208+
},
209+
"pw_watch": {
210+
"tagline": "Embedded development file system watcher",
211+
"status": "stable"
212+
}
213+
}

‎docs/module_metadata_schema.json

+54
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
{
2+
"description": "Schema for //docs/module_metadata.json.",
3+
"type": "object",
4+
"patternProperties": {
5+
"^pw_.*": {
6+
"description": "The metadata for each module must match this schema.",
7+
"type": "object",
8+
"properties": {
9+
"languages": {
10+
"description": "The programming languages that the module supports.",
11+
"type": "array",
12+
"items": {
13+
"type": "string",
14+
"enum": [
15+
"C",
16+
"C11",
17+
"C++",
18+
"C++17",
19+
"C++20",
20+
"CLI",
21+
"Java",
22+
"Python",
23+
"Rust",
24+
"Starlark",
25+
"TypeScript"
26+
]
27+
}
28+
},
29+
"size": {
30+
"description": "A summary of the code size impact of the module.",
31+
"type": "string"
32+
},
33+
"status": {
34+
"description": "The status of the module.",
35+
"type": "string",
36+
"enum": [
37+
"stable",
38+
"unstable",
39+
"experimental"
40+
]
41+
},
42+
"tagline": {
43+
"description": "A concise summary of the module's value proposition.",
44+
"type": "string"
45+
}
46+
},
47+
"required": [
48+
"status"
49+
],
50+
"additionalProperties": false
51+
}
52+
},
53+
"additionalProperties": false
54+
}

‎pw_alignment/docs.rst

-3
Original file line numberDiff line numberDiff line change
@@ -5,9 +5,6 @@ pw_alignment
55
============
66
.. pigweed-module::
77
:name: pw_alignment
8-
:tagline: Natural object alignment, guaranteed
9-
:status: stable
10-
:languages: C++17
118

129
- **Transparent**: Enforce natural alignment without any changes to how your
1310
objects are used.

‎pw_allocator/api.rst

-1
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,6 @@ API reference
55
=============
66
.. pigweed-module-subpage::
77
:name: pw_allocator
8-
:tagline: pw_allocator: Flexible, safe, and measurable memory allocation
98

109
This module provides the following:
1110

‎pw_allocator/code_size.rst

-1
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,6 @@ Code size analysis
55
==================
66
.. pigweed-module-subpage::
77
:name: pw_allocator
8-
:tagline: pw_allocator: Flexible, safe, and measurable memory allocation
98

109
This module provides several implementations of the
1110
:ref:`module-pw_allocator-api-allocator` interface. The tables below shows the

‎pw_allocator/design.rst

-1
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,6 @@ Design & roadmap
55
================
66
.. pigweed-module-subpage::
77
:name: pw_allocator
8-
:tagline: pw_allocator: Flexible, safe, and measurable memory allocation
98

109
----------------------------------
1110
Design of pw::allocator::Allocator

‎pw_allocator/docs.rst

-4
Original file line numberDiff line numberDiff line change
@@ -5,10 +5,6 @@ pw_allocator
55
============
66
.. pigweed-module::
77
:name: pw_allocator
8-
:tagline: Flexible, safe, and measurable memory allocation
9-
:status: unstable
10-
:languages: C++17
11-
:code-size-impact: 400 to 1800 bytes
128

139
- **Flexible**: Simple interface makes it easy to inject specific behaviors.
1410
- **Safe**: Can detect memory corruption, e.g overflows and use-after-free.

‎pw_allocator/guide.rst

-1
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,6 @@ Guides
55
======
66
.. pigweed-module-subpage::
77
:name: pw_allocator
8-
:tagline: pw_allocator: Flexible, safe, and measurable memory allocation
98

109
.. _module-pw_allocator-get-started:
1110

‎pw_async2/docs.rst

-3
Original file line numberDiff line numberDiff line change
@@ -5,9 +5,6 @@ pw_async2
55
=============
66
.. pigweed-module::
77
:name: pw_async2
8-
:tagline: Cooperative async tasks for embedded
9-
:status: experimental
10-
:languages: C++17
118

129
- **Simple Ownership**: Say goodbye to that jumble of callbacks and shared
1310
state! Complex tasks with many concurrent elements can be expressed by

‎pw_bluetooth_sapphire/docs.rst

-4
Original file line numberDiff line numberDiff line change
@@ -5,10 +5,6 @@ pw_bluetooth_sapphire
55
=====================
66
.. pigweed-module::
77
:name: pw_bluetooth_sapphire
8-
:tagline: Battle-tested Bluetooth with rock-solid reliability
9-
:status: unstable
10-
:languages: C++17
11-
:code-size-impact: 1.5 to 2 megabytes
128

139
.. attention::
1410
This module is still under construction. There is no public API yet. Please

‎pw_boot/docs.rst

-3
Original file line numberDiff line numberDiff line change
@@ -5,9 +5,6 @@ pw_boot
55
=======
66
.. pigweed-module::
77
:name: pw_boot
8-
:tagline: Simplified booting for embedded C++ targets
9-
:status: stable
10-
:languages: C++17
118

129
``pw_boot`` provides a linker script and some early initialization of static
1310
memory regions and C++ constructors. This is enough to get many targets booted

0 commit comments

Comments
 (0)