docs: Normalize SEED filenames

Currently SEED filenames start with the SEED number but then include arbitrary text, e.g. 0002-template.rst. Automation of the SEED index will be easier if we normalize the filenames to only include the number, e.g. 0002.rst. SEED URLs will also be more predictable, e.g. pigweed.dev/seed/0002.html. This is prereq work for the migration of the docgen system to Bazel; it will be hard to migrate the SEED index auto-generation to Bazel if we don't make this change. Bug: 318892911 Change-Id: If4cb3b8aa92fb11233f78062eddc22c7913d584b Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/248452 Reviewed-by: Alexei Frolov <[email protected]> Presubmit-Verified: CQ Bot Account <[email protected]> Commit-Queue: Kayce Basques <[email protected]> Pigweed-Auto-Submit: Kayce Basques <[email protected]> Lint: Lint 🤖 <[email protected]> Docs-Not-Needed: Kayce Basques <[email protected]>
google · Nov 21, 2024 · f4e18d1 · f4e18d1
1 parent 55f09ff
commit f4e18d1
Show file tree

Hide file tree

Showing 31 changed files with 77 additions and 54 deletions.
diff --git a/docs/conf.py b/docs/conf.py
@@ -236,6 +236,29 @@ def pygments_monkeypatch_style(mod_name, cls):
     'pw_sys_io_pico/docs': '../pw_sys_io_rp2040/docs.html',
     'pw_tokenizer/cli': './docs.html',
     'pw_tokenizer/guides': './docs.html',
+    'seed/0000-index': './0000.html',
+    'seed/0001-the-seed-process': './0001.html',
+    'seed/0002-template': './0002.html',
+    'seed/0101-pigweed.json': './0101.html',
+    'seed/0102-module-docs': './0102.html',
+    'seed/0103-pw_protobuf-past-present-future': './0103.html',
+    'seed/0104-display-support': './0104.html',
+    'seed/0105-pw_tokenizer-pw_log-nested-tokens': './0105.html',
+    'seed/0107-communications': './0107.html',
+    'seed/0108-pw_emu-emulators-frontend': './0108.html',
+    'seed/0109-comms-buffers': './0109.html',
+    'seed/0110-memory-allocation-interfaces': './0110.html',
+    'seed/0111-build-systems': './0111.html',
+    'seed/0112-async-poll': './0112.html',
+    'seed/0113-bazel-cc-toolchain-api': './0113.html',
+    'seed/0114-channels': './0114.html',
+    'seed/0117-pw_i3c': './0117.html',
+    'seed/0119-pw-sensor': './0119.html',
+    'seed/0120-pw-sensor-config': './0120.html',
+    'seed/0122-code-samples': './0122.html',
+    'seed/0124-multisink-size-info': './0124.html',
+    'seed/0128-abstracting-thread-creation': './0128.html',
+    'seed/0130-update-sphinx-theme': './0130.html',
     'seeds/index': '../seed/0000-index.html',
     'sense/index': '../docs/showcases/sense/',
     'tour/index': '../docs/showcases/sense/',

diff --git a/docs/contributing/index.rst b/docs/contributing/index.rst
@@ -431,7 +431,7 @@ See the warning about caching Python packages for multiple platforms in
    Code reviews (Gerrit) <https://pigweed-review.googlesource.com>
    ../code_reviews
    Issue tracker <https://issues.pigweed.dev/issues?q=status:open>
-   SEEDs <../../seed/0000-index>
+   SEEDs <../../seed/0000>
    ../infra/index
    ../embedded_cpp_guide
    ../style_guide

diff --git a/pw_emu/docs.rst b/pw_emu/docs.rst
@@ -118,4 +118,4 @@ Then run a binary like this!
    api
    config
    design
-   SEED-0108 <../seed/0108-pw_emu-emulators-frontend>
+   SEED-0108 <../seed/0108>
diff --git a/seed/0000-index.rst → seed/0000.rst b/seed/0000-index.rst → seed/0000.rst
diff --git a/seed/0001-the-seed-process.rst → seed/0001.rst b/seed/0001-the-seed-process.rst → seed/0001.rst
@@ -129,7 +129,7 @@ Suppose you'd like to propose a new Pigweed RPC Over Smoke Signals protocol.
    ``Pigweed-Auto-Submit`` to +1. This change will be approved promptly and
    lock in your assigned SEED number.
 
-   .. image:: 0001-the-seed-process/seed-index-gerrit.png
+   .. image:: 0001/seed-index-gerrit.png
 
 #. Fill out your proposal document, using the :ref:`SEED template<seed-0002>` as
    a guide.

diff --git a/...01-the-seed-process/seed-index-gerrit.png → seed/0001/seed-index-gerrit.png b/...01-the-seed-process/seed-index-gerrit.png → seed/0001/seed-index-gerrit.png
diff --git a/seed/0002-template.rst → seed/0002.rst b/seed/0002-template.rst → seed/0002.rst
diff --git a/seed/0101-pigweed.json.rst → seed/0101.rst b/seed/0101-pigweed.json.rst → seed/0101.rst
diff --git a/seed/0102-module-docs.rst → seed/0102.rst b/seed/0102-module-docs.rst → seed/0102.rst
diff --git a/.../0103-pw_protobuf-past-present-future.rst → seed/0103.rst b/.../0103-pw_protobuf-past-present-future.rst → seed/0103.rst
diff --git a/seed/0104-display-support.rst → seed/0104.rst b/seed/0104-display-support.rst → seed/0104.rst
diff --git a/...105-pw_tokenizer-pw_log-nested-tokens.rst → seed/0105.rst b/...105-pw_tokenizer-pw_log-nested-tokens.rst → seed/0105.rst
diff --git a/seed/0107-communications.rst → seed/0107.rst b/seed/0107-communications.rst → seed/0107.rst
diff --git a/seed/0108-pw_emu-emulators-frontend.rst → seed/0108.rst b/seed/0108-pw_emu-emulators-frontend.rst → seed/0108.rst
diff --git a/seed/0109-comms-buffers.rst → seed/0109.rst b/seed/0109-comms-buffers.rst → seed/0109.rst
diff --git a/seed/0110-memory-allocation-interfaces.rst → seed/0110.rst b/seed/0110-memory-allocation-interfaces.rst → seed/0110.rst
diff --git a/seed/0111-build-systems.rst → seed/0111.rst b/seed/0111-build-systems.rst → seed/0111.rst
diff --git a/seed/0112-async-poll.rst → seed/0112.rst b/seed/0112-async-poll.rst → seed/0112.rst
diff --git a/seed/0113-bazel-cc-toolchain-api.rst → seed/0113.rst b/seed/0113-bazel-cc-toolchain-api.rst → seed/0113.rst
diff --git a/seed/0114-channels.rst → seed/0114.rst b/seed/0114-channels.rst → seed/0114.rst
diff --git a/seed/0117-pw_i3c.rst → seed/0117.rst b/seed/0117-pw_i3c.rst → seed/0117.rst
diff --git a/seed/0119-pw-sensor.rst → seed/0119.rst b/seed/0119-pw-sensor.rst → seed/0119.rst
@@ -82,15 +82,15 @@ concepts:
   available, the sensor framework will demux the data and provide it to the
   various clients based on the live ``Connection``\s.
 
-.. image:: 0119-pw-sensor/high-level-view.svg
+.. image:: 0119/high-level-view.svg
 
 Actually reading the data is a 2 step process. The first is getting the data
 from the ``Sensor`` object. The second step is decoding it into something
 that's usable. Data from the first step is generally still in register format
 and includes some headers from the driver which will allow the ``Decoder`` to
 convert the values to the appropriate representation (most likely ``float``).
 
-.. image:: 0119-pw-sensor/data-pipeline.svg
+.. image:: 0119/data-pipeline.svg
 
 -----------------
 The Sensor Driver

diff --git a/seed/0119-pw-sensor/data-pipeline.svg → seed/0119/data-pipeline.svg b/seed/0119-pw-sensor/data-pipeline.svg → seed/0119/data-pipeline.svg
diff --git a/seed/0119-pw-sensor/high-level-view.svg → seed/0119/high-level-view.svg b/seed/0119-pw-sensor/high-level-view.svg → seed/0119/high-level-view.svg
diff --git a/seed/0120-pw-sensor-config.rst → seed/0120.rst b/seed/0120-pw-sensor-config.rst → seed/0120.rst
diff --git a/seed/0122-code-samples.rst → seed/0122.rst b/seed/0122-code-samples.rst → seed/0122.rst
diff --git a/seed/0124-multisink-size-info.rst → seed/0124.rst b/seed/0124-multisink-size-info.rst → seed/0124.rst
diff --git a/seed/0128-abstracting-thread-creation.rst → seed/0128.rst b/seed/0128-abstracting-thread-creation.rst → seed/0128.rst
diff --git a/seed/0130-update-sphinx-theme.rst → seed/0130.rst b/seed/0130-update-sphinx-theme.rst → seed/0130.rst
diff --git a/seed/BUILD.bazel b/seed/BUILD.bazel
@@ -22,29 +22,29 @@ sphinx_docs_library(
     srcs = [
         # TODO: https://pwbug.dev/378559626 - Refactor this auto-generated
         # page to support Bazel-based docgen.
-        "0000-index.rst",
-        "0001-the-seed-process.rst",
-        "0002-template.rst",
-        "0101-pigweed.json.rst",
-        "0102-module-docs.rst",
-        "0103-pw_protobuf-past-present-future.rst",
-        "0104-display-support.rst",
-        "0105-pw_tokenizer-pw_log-nested-tokens.rst",
-        "0107-communications.rst",
-        "0108-pw_emu-emulators-frontend.rst",
-        "0109-comms-buffers.rst",
-        "0110-memory-allocation-interfaces.rst",
-        "0111-build-systems.rst",
-        "0112-async-poll.rst",
-        "0113-bazel-cc-toolchain-api.rst",
-        "0114-channels.rst",
-        "0117-pw_i3c.rst",
-        "0119-pw-sensor.rst",
-        "0120-pw-sensor-config.rst",
-        "0122-code-samples.rst",
-        "0124-multisink-size-info.rst",
-        "0128-abstracting-thread-creation.rst",
-        "0130-update-sphinx-theme.rst",
+        "0000.rst",
+        "0001.rst",
+        "0002.rst",
+        "0101.rst",
+        "0102.rst",
+        "0103.rst",
+        "0104.rst",
+        "0105.rst",
+        "0107.rst",
+        "0108.rst",
+        "0109.rst",
+        "0110.rst",
+        "0111.rst",
+        "0112.rst",
+        "0113.rst",
+        "0114.rst",
+        "0117.rst",
+        "0119.rst",
+        "0120.rst",
+        "0122.rst",
+        "0124.rst",
+        "0128.rst",
+        "0130.rst",
     ],
     prefix = "seed/",
     target_compatible_with = incompatible_with_mcu(),

diff --git a/seed/BUILD.gn b/seed/BUILD.gn
@@ -17,56 +17,56 @@ import("//build_overrides/pigweed.gni")
 import("seed.gni")
 
 pw_seed("0001") {
-  sources = [ "0001-the-seed-process.rst" ]
-  inputs = [ "0001-the-seed-process/seed-index-gerrit.png" ]
+  sources = [ "0001.rst" ]
+  inputs = [ "0001/seed-index-gerrit.png" ]
   title = "The SEED Process"
   status = "Meta"
   author = "The Pigweed Authors"
   facilitator = "N/A"
 }
 
 pw_seed("0002") {
-  sources = [ "0002-template.rst" ]
+  sources = [ "0002.rst" ]
   title = "SEED Template"
   status = "Meta"
   author = "The Pigweed Authors"
   facilitator = "N/A"
 }
 
 pw_seed("0101") {
-  sources = [ "0101-pigweed.json.rst" ]
+  sources = [ "0101.rst" ]
   title = "pigweed.json"
   status = "Accepted"
   author = "Rob Mohr"
   facilitator = "Ted Pudlik"
 }
 
 pw_seed("0102") {
-  sources = [ "0102-module-docs.rst" ]
+  sources = [ "0102.rst" ]
   title = "Consistent Module Documentation"
   status = "Accepted"
   author = "Chad Norvell"
   facilitator = "Kayce Basques"
 }
 
 pw_seed("0103") {
-  sources = [ "0103-pw_protobuf-past-present-future.rst" ]
+  sources = [ "0103.rst" ]
   title = "pw_protobuf: Past, present, and future"
   status = "Accepted"
   author = "Alexei Frolov"
   facilitator = "Armando Montanez"
 }
 
 pw_seed("0104") {
-  sources = [ "0104-display-support.rst" ]
+  sources = [ "0104.rst" ]
   title = "Display Support"
   status = "Accepted"
   author = "Chris Mumford"
   facilitator = "Anthony DiGirolamo"
 }
 
 pw_seed("0105") {
-  sources = [ "0105-pw_tokenizer-pw_log-nested-tokens.rst" ]
+  sources = [ "0105.rst" ]
   title = "Nested Tokens and Tokenized Log Arguments"
   status = "Accepted"
   author = "Gwyneth Chen"
@@ -82,63 +82,63 @@ pw_seed("0106") {
 }
 
 pw_seed("0107") {
-  sources = [ "0107-communications.rst" ]
+  sources = [ "0107.rst" ]
   title = "Pigweed Communications"
   status = "Accepted"
   author = "Wyatt Hepler"
   facilitator = "Carlos Chinchilla"
 }
 
 pw_seed("0108") {
-  sources = [ "0108-pw_emu-emulators-frontend.rst" ]
+  sources = [ "0108.rst" ]
   title = "Emulators Frontend"
   status = "Accepted"
   author = "Octavian Purdila"
   facilitator = "Armando Montanez"
 }
 
 pw_seed("0109") {
-  sources = [ "0109-comms-buffers.rst" ]
+  sources = [ "0109.rst" ]
   title = "Communication Buffers"
   status = "Accepted"
   author = "Taylor Cramer"
   facilitator = "Erik Gilling"
 }
 
 pw_seed("0110") {
-  sources = [ "0110-memory-allocation-interfaces.rst" ]
+  sources = [ "0110.rst" ]
   title = "Memory Allocation Interfaces"
   status = "Accepted"
   author = "Alexei Frolov"
   facilitator = "Taylor Cramer"
 }
 
 pw_seed("0111") {
-  sources = [ "0111-build-systems.rst" ]
+  sources = [ "0111.rst" ]
   title = "Make Bazel Pigweed's Primary Build System"
   status = "Accepted"
   author = "Ted Pudlik"
   facilitator = "Armando Montanez"
 }
 
 pw_seed("0112") {
-  sources = [ "0112-async-poll.rst" ]
+  sources = [ "0112.rst" ]
   title = "Async Poll Model"
   status = "Accepted"
   author = "Taylor Cramer"
   facilitator = "Wyatt Hepler"
 }
 
 pw_seed("0113") {
-  sources = [ "0113-bazel-cc-toolchain-api.rst" ]
+  sources = [ "0113.rst" ]
   title = "Add modular Bazel C/C++ toolchain API"
   status = "Accepted"
   author = "Armando Montanez"
   facilitator = "Ted Pudlik"
 }
 
 pw_seed("0114") {
-  sources = [ "0114-channels.rst" ]
+  sources = [ "0114.rst" ]
   title = "Channels"
   status = "Accepted"
   author = "Wyatt Hepler"
@@ -162,7 +162,7 @@ pw_seed("0116") {
 }
 
 pw_seed("0117") {
-  sources = [ "0117-pw_i3c.rst" ]
+  sources = [ "0117.rst" ]
   title = "pw_i3c"
   status = "Accepted"
   author = "Jack Chen"
@@ -177,18 +177,18 @@ pw_seed("0118") {
 }
 
 pw_seed("0119") {
-  sources = [ "0119-pw-sensor.rst" ]
+  sources = [ "0119.rst" ]
   title = "pw_sensor A sensor framework"
   status = "Accepted"
   inputs = [
-    "0119-pw-sensor/high-level-view.svg",
-    "0119-pw-sensor/data-pipeline.svg",
+    "0119/high-level-view.svg",
+    "0119/data-pipeline.svg",
   ]
   author = "Yuval Peress"
 }
 
 pw_seed("0120") {
-  sources = [ "0120-pw-sensor-config.rst" ]
+  sources = [ "0120.rst" ]
   status = "Accepted"
   title = "pw_sensor Sensor configuration"
   author = "Yuval Peress"
@@ -202,7 +202,7 @@ pw_seed("0121") {
 }
 
 pw_seed("0122") {
-  sources = [ "0122-code-samples.rst" ]
+  sources = [ "0122.rst" ]
   title = "Organize Pigweed code samples"
   status = "Accepted"
   author = "Ted Pudlik"
@@ -218,7 +218,7 @@ pw_seed("0123") {
 }
 
 pw_seed("0124") {
-  sources = [ "0124-multisink-size-info.rst" ]
+  sources = [ "0124.rst" ]
   title = "Interfaces for Retrieving Size Information from Multisink"
   status = "Intent Approved"
   author = "Jiacheng Lu"
@@ -250,7 +250,7 @@ pw_seed("0128") {
   title = "Abstracting Thread Creation"
   author = "Wyatt Hepler"
   status = "Accepted"
-  sources = [ "0128-abstracting-thread-creation.rst" ]
+  sources = [ "0128.rst" ]
   facilitator = "Taylor Cramer"
 }
 
@@ -265,7 +265,7 @@ pw_seed("0130") {
   title = "Update Sphinx theme"
   author = "Kayce Basques"
   status = "Accepted"
-  sources = [ "0130-update-sphinx-theme.rst" ]
+  sources = [ "0130.rst" ]
 }
 
 pw_seed("0132") {
@@ -278,7 +278,7 @@ pw_seed("0132") {
 # This must be defined after all `pw_seed` targets, as it relies on information
 # exposed by them.
 pw_seed_index("seeds") {
-  index_file = "0000-index.rst"
+  index_file = "0000.rst"
   seeds = [
     ":0001",
     ":0002",
-Original file line number
+Diff line change
@@ Expand Up / @@ -118,4 +118,4 @@ Then run a binary like this! @@
        api
        config
        design
-       SEED-0108 <../seed/0108-pw_emu-emulators-frontend>
+       SEED-0108 <../seed/0108>