pw_emu: Link all the docs to each other

Change-Id: I5208afedfa4930e9e7861b511c8a6d760f79f172
Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/184310
Reviewed-by: Kayce Basques <[email protected]>
Commit-Queue: Kayce Basques <[email protected]>
Reviewed-by: Keir Mierle <[email protected]>

docs/contributing/module_docs.rst

@@ -157,17 +157,61 @@ your module. The filenames should be ``get_started.rst`` and ``guides.rst``.
 ``Design & Roadmap`` can also be split into 2 docs. The filenames should be
 ``design.rst`` and ``roadmap.rst``.
 
-Nav cards
----------
-When using the multi-page approach, every page in the set must link to every
-other page in the set. We recommend using the ``grid`` directive to create
-call-to-action buttons on the bottom of every page. See ``//pw_string/docs.rst``
-for an example.
+Link each doc to all other docs in the set
+------------------------------------------
+Each doc must link to all other docs in the set. Here's how we currently do it.
+We may adjust our approach in the future if we find a better solution.
 
-.. note::
+#. Create a grid of nav cards at the bottom of ``docs.rst``. Example:
+
+   .. code-block::
+
+      .. pw_<name>-nav-start
+
+      .. grid:: 1
+
+         .. grid-item-card:: :octicon:`rocket` Get started & guides
+            :link: module-pw_emu-guide
+            :link-type: ref
+            :class-item: sales-pitch-cta-primary
+
+            How to set up and use ``pw_<name>``
+
+      .. grid:: 2
+
+         .. grid-item-card:: :octicon:`terminal` CLI reference
+            :link: module-pw_emu-cli
+            :link-type: ref
+            :class-item: sales-pitch-cta-secondary
+
+            Reference details about the ``pw_<name>`` command line interface
+
+         .. grid-item-card:: :octicon:`code-square` API reference
+            :link: module-pw_emu-api
+            :link-type: ref
+            :class-item: sales-pitch-cta-secondary
+
+            Reference details about the ``pw_<name>`` Python API
+
+      .. pw_<name>-nav-end
+
+   Note the ``.. pw_<name>-nav-start`` and ``.. pw_<name>-nav-end`` comments.
+   You'll use these in the next step.
+
+#. Add the following H2 section to the bottom of every other doc in the set.
+
+   .. code-block::
+
+      -------------------
+      More pw_<name> docs
+      -------------------
+      .. include:: docs.rst
+         :start-after: .. pw_<name>-nav-start
+         :end-before: .. pw_<name>-nav-end
+
+Examples:
 
-   We will eventually automate this. We know it's error-prone and tedious to
-   do this manually.
+* :ref:`module-pw_emu`
 
 ------------------
 Content guidelines

pw_emu/api.rst

@@ -44,4 +44,9 @@ pw_emu.core.Launcher
    :members:
    :private-members: _config, _handles, _pre_start, _post_start, _get_connector
 
-11:08:20
+----------------
+More pw_emu docs
+----------------
+.. include:: docs.rst
+   :start-after: .. pw_emu-nav-start
+   :end-before: .. pw_emu-nav-end

pw_emu/cli.rst

@@ -14,3 +14,10 @@ CLI reference
    :nodefaultconst:
    :nodescription:
    :noepilog:
+
+----------------
+More pw_emu docs
+----------------
+.. include:: docs.rst
+   :start-after: .. pw_emu-nav-start
+   :end-before: .. pw_emu-nav-end

pw_emu/config.rst

@@ -236,3 +236,10 @@ The following expressions are substituted in configuration strings, including
 
 * ``$pw_env{envvar}`` - Replaces the statement with the value of ``envvar``.
   If ``envvar`` doesn't exist a configuration error is raised.
+
+----------------
+More pw_emu docs
+----------------
+.. include:: docs.rst
+   :start-after: .. pw_emu-nav-start
+   :end-before: .. pw_emu-nav-end

pw_emu/design.rst

@@ -104,3 +104,10 @@ allocate a port dynamically:
 There is a race condition that allows another program to fetch the same port,
 but it should work in most light use cases until the issue is properly resolved
 upstream.
+
+----------------
+More pw_emu docs
+----------------
+.. include:: docs.rst
+   :start-after: .. pw_emu-nav-start
+   :end-before: .. pw_emu-nav-end

pw_emu/docs.rst

@@ -51,6 +51,8 @@ Then run a binary like this!
    pw emu run --args=-no-reboot qemu-lm3s6965evb \
        out/lm3s6965evb_qemu_gcc_size_optimized/obj/pw_snapshot/test/cpp_compile_test
 
+.. pw_emu-nav-start
+
 .. grid:: 1
 
    .. grid-item-card:: :octicon:`rocket` Get started & guides
@@ -108,6 +110,8 @@ Then run a binary like this!
 
       Source code for ``pw_emu``
 
+.. pw_emu-nav-end
+
 .. toctree::
    :hidden:
    :maxdepth: 1

pw_emu/guide.rst

@@ -345,3 +345,10 @@ connector, like :py:meth:`pw_emu.core.Connector.reset` and
 internal channels and :py:class:`pw_emu.core.Connector.get_channel_stream`. See
 :py:class:`pw_emu.core.Connector` for a complete list of the abstract methods
 that need to be implemented.
+
+----------------
+More pw_emu docs
+----------------
+.. include:: docs.rst
+   :start-after: .. pw_emu-nav-start
+   :end-before: .. pw_emu-nav-end