pw_docgen: Add module metadata extension
Change-Id: I65b161389260e863466c137c6971e82ae50d4d0a
Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/129580
Reviewed-by: Anthony DiGirolamo <[email protected]>
Commit-Queue: Chad Norvell <[email protected]>
diff --git a/pw_docgen/docs.rst b/pw_docgen/docs.rst
index 5528ea1..6971384 100644
--- a/pw_docgen/docs.rst
+++ b/pw_docgen/docs.rst
@@ -168,6 +168,52 @@
This module houses Pigweed-specific extensions for the Sphinx documentation
generator. Extensions are included and configured in ``docs/conf.py``.
+module_metadata
+---------------
+Per :ref:`SEED-0102 <seed-0102>`, Pigweed module documentation has a standard
+format. The ``pigweed-module`` Sphinx directive provides that format and
+registers module metadata that can be used elsewhere in the Sphinx build.
+
+We need to add the directive after the document title, and add a class *to*
+the document title to achieve the title & subtitle formatting. Here's an
+example:
+
+.. code-block:: rst
+
+ .. rst-class:: with-subtitle
+
+ =========
+ pw_string
+ =========
+
+ .. pigweed-module::
+ :name: pw_string
+ :tagline: Efficient, easy, and safe string manipulation
+ :status: stable
+ :languages: C++14, C++17
+ :code-size-impact: 500 to 1500 bytes
+ :get-started: module-pw_string-get-started
+ :design: module-pw_string-design
+ :guides: module-pw_string-guide
+ :api: module-pw_string-api
+
+ Module sales pitch goes here!
+
+Directive options
+_________________
+- ``name``: The module name (required)
+- ``tagline``: A very short tagline that summarizes the module (required)
+- ``status``: One of ``experimental``, ``unstable``, and ``stable`` (required)
+- ``is-deprecated``: A flag indicating that the module is deprecated
+- ``languages``: A comma-separated list of languages the module supports
+- ``code-size-impact``: A summarize of the average code size impact
+- ``get-started``: A reference to the getting started section (required)
+- ``tutorials``: A reference to the tutorials section
+- ``guides``: A reference to the guides section
+- ``design``: A reference to the design considerations section (required)
+- ``concepts``: A reference to the concepts documentation
+- ``api``: A reference to the API documentation
+
google_analytics
----------------
When this extension is included and a ``google_analytics_id`` is set in the
