docs: Make labels consistent; remove boilerplate
- Update labels so they use consistent naming. Instead of the
copy-and-pasted `chapter` prefix, name labels with a prefix consistent
with what they point to:
- "module-" for module
- "target-" for targets
- "docs-" for general documentation
- Remove the unnecessary highlight and default-domain directives.
Neither is necessary since the Pigweed docs always specify the
language in code snippets and other directives.
Change-Id: I55c34e9ec919f6f4670e5d3d008e0edf5fecf05b
Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/19328
Commit-Queue: Wyatt Hepler <hepler@google.com>
Reviewed-by: Keir Mierle <keir@google.com>
diff --git a/docker/docs.rst b/docker/docs.rst
index a5e26c0..ed6a290 100644
--- a/docker/docs.rst
+++ b/docker/docs.rst
@@ -1,5 +1,3 @@
-.. _chapter-docker:
-
------
docker
------
diff --git a/docs/build_system.rst b/docs/build_system.rst
index 799a118..9c0b2e6 100644
--- a/docs/build_system.rst
+++ b/docs/build_system.rst
@@ -1,5 +1,4 @@
-.. _chapter-build-system:
-
+.. _docs-build-system:
============
Build system
@@ -52,14 +51,14 @@
* Image signing
* Creating databases of symbols for debugging
* Extracting string tokens into a database (for example, with
- :ref:`chapter-pw-tokenizer`)
+ :ref:`module-pw_tokenizer`)
These are run as steps during a build, facilitated by the build system.
See also
^^^^^^^^
-* :ref:`pw-build-python-script`
+* :ref:`module-pw_build-python-script`
Python packaging
----------------
@@ -80,7 +79,7 @@
See also
^^^^^^^^
-* :ref:`chapter-pw-bloat`
+* :ref:`module-pw_bloat`
Documentation
-------------
@@ -92,7 +91,7 @@
See also
^^^^^^^^
-* :ref:`chapter-pw-docgen`
+* :ref:`module-pw_docgen`
Unit testing
------------
@@ -118,8 +117,8 @@
See also
^^^^^^^^
-* :ref:`chapter-pw-unit-test`
-* :ref:`chapter-pw-target-runner`
+* :ref:`module-pw_unit_test`
+* :ref:`module-pw_target_runner`
Bonus: pw watch
---------------
@@ -136,7 +135,7 @@
See also
^^^^^^^^
-* :ref:`chapter-pw-watch`
+* :ref:`module-pw_watch`
Pigweed's build systems
=======================
@@ -415,7 +414,7 @@
To build for a specific hardware platform, builds define Pigweed targets. These
are essentially GN toolchains which set special arguments telling Pigweed how to
build. For information on Pigweed's target system, refer to
-:ref:`chapter-targets`.
+:ref:`docs-targets`.
The dummy toolchain
-------------------
diff --git a/docs/embedded_cpp_guide.rst b/docs/embedded_cpp_guide.rst
index b05832c..4d7a669 100644
--- a/docs/embedded_cpp_guide.rst
+++ b/docs/embedded_cpp_guide.rst
@@ -1,8 +1,4 @@
-.. _chapter-embedded-cpp:
-
-.. default-domain:: cpp
-
-.. highlight:: sh
+.. _docs-embedded-cpp:
==================
Embedded C++ Guide
diff --git a/docs/faq.rst b/docs/faq.rst
index 090c08e..3b51b4a 100644
--- a/docs/faq.rst
+++ b/docs/faq.rst
@@ -1,4 +1,4 @@
-.. _chapter-faq:
+.. _docs-faq:
--------------------------
Frequently Asked Questions
@@ -33,7 +33,7 @@
Isn't C++ bloated and slow?
---------------------------
In general, no, but it is important to follow some guidelines as discussed in
-the :ref:`Embedded C++ Guide <chapter-embedded-cpp>`.
+the :ref:`Embedded C++ Guide <docs-embedded-cpp>`.
At Google, we have made some quantitative analysis of various common embedded
patterns in C++ to evaluate the cost of various constructs. We will open source
diff --git a/docs/index.rst b/docs/index.rst
index a7230ed..9a02eca 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,5 +1,3 @@
-.. _chapter-home:
-
.. highlight:: sh
.. mdinclude:: README.md
diff --git a/docs/module_guides.rst b/docs/module_guides.rst
index 728deff..f45131e 100644
--- a/docs/module_guides.rst
+++ b/docs/module_guides.rst
@@ -1,3 +1,5 @@
+.. _docs-module-guides:
+
=============
Module Guides
=============
diff --git a/docs/module_structure.rst b/docs/module_structure.rst
index f3556b3..89ec692 100644
--- a/docs/module_structure.rst
+++ b/docs/module_structure.rst
@@ -1,8 +1,4 @@
-.. default-domain:: cpp
-
-.. highlight:: sh
-
-.. _chapter-module-guide:
+.. _docs-module-structure:
----------------
Module Structure
@@ -264,8 +260,8 @@
- Add in ``docs/BUILD.gn`` to ``pw_doc_gen("docs")``
-11. Run :ref:`chapter-module-module-check`
+11. Run :ref:`module-pw_module-module-check`
- ``$ pw module-check {pw_module_dir}``
-12. Contribute your module to upstream Pigweed (optional but encouraged!)
\ No newline at end of file
+12. Contribute your module to upstream Pigweed (optional but encouraged!)
diff --git a/docs/style_guide.rst b/docs/style_guide.rst
index 104fe73..320aac3 100644
--- a/docs/style_guide.rst
+++ b/docs/style_guide.rst
@@ -1,8 +1,4 @@
-.. _chapter-style:
-
-.. default-domain:: cpp
-
-.. highlight:: sh
+.. _docs-pw-style:
===========================
Style Guide and Conventions
diff --git a/docs/targets.rst b/docs/targets.rst
index 19ee129..8ada893 100644
--- a/docs/targets.rst
+++ b/docs/targets.rst
@@ -1,4 +1,4 @@
-.. _chapter-targets:
+.. _docs-targets:
=======
Targets
diff --git a/pw_allocator/docs.rst b/pw_allocator/docs.rst
index 6cb05f4..853cb08 100644
--- a/pw_allocator/docs.rst
+++ b/pw_allocator/docs.rst
@@ -1,6 +1,4 @@
-.. _chapter-pw-allocator:
-
-.. default-domain:: cpp
+.. _module-pw_allocator:
------------
pw_allocator
diff --git a/pw_arduino_build/docs.rst b/pw_arduino_build/docs.rst
index 638fd94..6db47e3 100644
--- a/pw_arduino_build/docs.rst
+++ b/pw_arduino_build/docs.rst
@@ -1,8 +1,4 @@
-.. default-domain:: cpp
-
-.. highlight:: sh
-
-.. _chapter-pw-arduino-build:
+.. _module-pw_arduino_build:
-----------------
pw_arduino_build
@@ -12,7 +8,7 @@
line utility and an `Arduino Main Wrapper`_.
.. seealso::
- See the :ref:`chapter-arduino` target documentation for a list of supported
+ See the :ref:`target-arduino` target documentation for a list of supported
hardware.
Arduino Main Wrapper
@@ -43,7 +39,7 @@
void loop() {}
.. note::
- ``pw_arduino_Init()`` initializes the :ref:`chapter-pw-sys-io-arduino`
+ ``pw_arduino_Init()`` initializes the :ref:`module-pw_sys_io_arduino`
module.
.. warning::
diff --git a/pw_assert/docs.rst b/pw_assert/docs.rst
index 4c2a63e..2d96c60 100644
--- a/pw_assert/docs.rst
+++ b/pw_assert/docs.rst
@@ -1,8 +1,4 @@
-.. _chapter-pw-assert:
-
-.. default-domain:: cpp
-
-.. highlight:: cpp
+.. _module-pw_assert:
=========
pw_assert
@@ -488,7 +484,7 @@
the backend could store crash details like the current thread's stack to flash.
This facade module (``pw_assert``) does not provide a backend. See
-:ref:`chapter-pw-assert-basic` for a basic implementation.
+:ref:`module-pw_assert_basic` for a basic implementation.
.. attention::
@@ -549,7 +545,7 @@
.. tip::
- See :ref:`chapter-pw-assert-basic` for one way to combine these arguments
+ See :ref:`module-pw_assert_basic` for one way to combine these arguments
into a meaningful error message.
Additionally, the backend must provide a link-time function for the light
diff --git a/pw_assert_basic/docs.rst b/pw_assert_basic/docs.rst
index bc649d2..45ff8f7 100644
--- a/pw_assert_basic/docs.rst
+++ b/pw_assert_basic/docs.rst
@@ -1,8 +1,4 @@
-.. default-domain:: cpp
-
-.. highlight:: cpp
-
-.. _chapter-pw-assert-basic:
+.. _module-pw_assert_basic:
===============
pw_assert_basic
diff --git a/pw_assert_log/docs.rst b/pw_assert_log/docs.rst
index 5a79527..012e1c8 100644
--- a/pw_assert_log/docs.rst
+++ b/pw_assert_log/docs.rst
@@ -1,8 +1,4 @@
-.. default-domain:: cpp
-
-.. highlight:: cpp
-
-.. _chapter-pw-assert-log:
+.. _module-pw_assert_log:
=============
pw_assert_log
diff --git a/pw_base64/docs.rst b/pw_base64/docs.rst
index 3872e3e..9013341 100644
--- a/pw_base64/docs.rst
+++ b/pw_base64/docs.rst
@@ -1,8 +1,4 @@
-.. _chapter-pw-base64:
-
-.. default-domain:: cpp
-
-.. highlight:: sh
+.. _module-pw_base64:
---------
pw_base64
diff --git a/pw_bloat/docs.rst b/pw_bloat/docs.rst
index 4faa7a5..8c00345 100644
--- a/pw_bloat/docs.rst
+++ b/pw_bloat/docs.rst
@@ -1,8 +1,4 @@
-.. default-domain:: cpp
-
-.. highlight:: sh
-
-.. _chapter-pw-bloat:
+.. _module-pw_bloat:
--------
pw_bloat
diff --git a/pw_blob_store/docs.rst b/pw_blob_store/docs.rst
index e3673b1..a84a22e 100644
--- a/pw_blob_store/docs.rst
+++ b/pw_blob_store/docs.rst
@@ -1,8 +1,4 @@
-.. _chapter-pw-blob_store:
-
-.. default-domain:: cpp
-
-.. highlight:: cpp
+.. _module-pw_blob_store:
-------------
pw_blob_store
diff --git a/pw_boot_armv7m/docs.rst b/pw_boot_armv7m/docs.rst
index 74bdd86..d00bec4 100644
--- a/pw_boot_armv7m/docs.rst
+++ b/pw_boot_armv7m/docs.rst
@@ -1,8 +1,4 @@
-.. _chapter-pw-boot-armv7m:
-
-.. default-domain:: cpp
-
-.. highlight:: sh
+.. _module-pw_boot_armv7m:
--------------
pw_boot_armv7m
diff --git a/pw_build/docs.rst b/pw_build/docs.rst
index 9fa2944..b27ac03 100644
--- a/pw_build/docs.rst
+++ b/pw_build/docs.rst
@@ -1,8 +1,4 @@
-.. default-domain:: cpp
-
-.. highlight:: sh
-
-.. _chapter-pw-build:
+.. _module-pw_build:
--------
pw_build
@@ -79,7 +75,7 @@
All of the ``pw_*`` target type overrides accept any arguments, as they simply
forward them through to the underlying target.
-.. _pw-build-python-script:
+.. _module-pw_build-python-script:
pw_python_script
^^^^^^^^^^^^^^^^
diff --git a/pw_bytes/docs.rst b/pw_bytes/docs.rst
index 39c5c5d..01b5e0f 100644
--- a/pw_bytes/docs.rst
+++ b/pw_bytes/docs.rst
@@ -1,8 +1,4 @@
-.. _chapter-pw-bytes:
-
-.. default-domain:: cpp
-
-.. highlight:: sh
+.. _module-pw_bytes:
---------
pw_bytes
diff --git a/pw_checksum/docs.rst b/pw_checksum/docs.rst
index 8d5f849..3006ab0 100644
--- a/pw_checksum/docs.rst
+++ b/pw_checksum/docs.rst
@@ -1,8 +1,4 @@
-.. default-domain:: cpp
-
-.. highlight:: sh
-
-.. _chapter-pw-checksum:
+.. _module-pw_checksum:
-----------
pw_checksum
diff --git a/pw_cli/docs.rst b/pw_cli/docs.rst
index fca0fa0..5d03f05 100644
--- a/pw_cli/docs.rst
+++ b/pw_cli/docs.rst
@@ -1,8 +1,4 @@
-.. _chapter-pw-cli:
-
-.. default-domain:: python
-
-.. highlight:: sh
+.. _module-pw_cli:
------
pw_cli
diff --git a/pw_containers/docs.rst b/pw_containers/docs.rst
index 3561936..dd36fc5 100644
--- a/pw_containers/docs.rst
+++ b/pw_containers/docs.rst
@@ -1,6 +1,4 @@
-.. default-domain:: cpp
-
-.. highlight:: sh
+.. _module-pw_containers:
-------------
pw_containers
diff --git a/pw_cpu_exception/docs.rst b/pw_cpu_exception/docs.rst
index 99ff6ac..ec4892b 100644
--- a/pw_cpu_exception/docs.rst
+++ b/pw_cpu_exception/docs.rst
@@ -1,8 +1,4 @@
-.. _chapter-pw-cpu-exception:
-
-.. default-domain:: cpp
-
-.. highlight:: cpp
+.. _module-pw_cpu_exception:
----------------
pw_cpu_exception
diff --git a/pw_cpu_exception_armv7m/docs.rst b/pw_cpu_exception_armv7m/docs.rst
index d55339f..9c79720 100644
--- a/pw_cpu_exception_armv7m/docs.rst
+++ b/pw_cpu_exception_armv7m/docs.rst
@@ -1,8 +1,4 @@
-.. _chapter-cpu-exception-armv7m:
-
-.. default-domain:: cpp
-
-.. highlight:: sh
+.. _module-pw_cpu_exception_armv7m:
-----------------------
pw_cpu_exception_armv7m
diff --git a/pw_docgen/docs.rst b/pw_docgen/docs.rst
index 8e9b05f..041893e 100644
--- a/pw_docgen/docs.rst
+++ b/pw_docgen/docs.rst
@@ -1,8 +1,4 @@
-.. default-domain:: cpp
-
-.. highlight:: sh
-
-.. _chapter-pw-docgen:
+.. _module-pw_docgen:
---------
pw_docgen
diff --git a/pw_doctor/docs.rst b/pw_doctor/docs.rst
index a9ddd99..51087a5 100644
--- a/pw_doctor/docs.rst
+++ b/pw_doctor/docs.rst
@@ -1,4 +1,4 @@
-.. _chapter-pw-doctor:
+.. _module-pw_doctor:
---------
pw_doctor
diff --git a/pw_env_setup/docs.rst b/pw_env_setup/docs.rst
index ed5fba3..9859144 100644
--- a/pw_env_setup/docs.rst
+++ b/pw_env_setup/docs.rst
@@ -1,4 +1,4 @@
-.. _chapter-pw-env_setup:
+.. _module-pw_env_setup:
------------
pw_env_setup
diff --git a/pw_fuzzer/docs.rst b/pw_fuzzer/docs.rst
index 4c94a91..baf34ce 100644
--- a/pw_fuzzer/docs.rst
+++ b/pw_fuzzer/docs.rst
@@ -1,8 +1,4 @@
-.. default-domain:: cpp
-
-.. highlight:: sh
-
-.. _chapter-pw-fuzzer:
+.. _module-pw_fuzzer:
---------
pw_fuzzer
diff --git a/pw_hdlc_lite/docs.rst b/pw_hdlc_lite/docs.rst
index 7b76bcf..e42d917 100644
--- a/pw_hdlc_lite/docs.rst
+++ b/pw_hdlc_lite/docs.rst
@@ -1,8 +1,4 @@
-.. default-domain:: cpp
-
-.. highlight:: sh
-
-.. _chapter-pw-hdlc-lite:
+.. _module-pw_hdlc_lite:
------------
pw_hdlc_lite
@@ -15,7 +11,7 @@
The ``pw_hdlc_lite`` module provides a simple, robust frame-oriented
transport that uses a subset of the HDLC protocol. ``pw_hdlc_lite`` supports
sending between embedded devices or the host. It can be used with
-:ref:`chapter-pw-rpc` to enable remote procedure calls (RPCs) on embedded on
+:ref:`module-pw_rpc` to enable remote procedure calls (RPCs) on embedded on
devices.
**Why use the pw_hdlc_lite module?**
@@ -28,8 +24,8 @@
.. admonition:: Try it out!
- For an example of how to use HDLC with :ref:`chapter-pw-rpc`, see the
- :ref:`chapter-pw-hdlc-rpc-example`.
+ For an example of how to use HDLC with :ref:`module-pw_rpc`, see the
+ :ref:`module-pw_hdlc_lite-rpc-example`.
.. toctree::
:maxdepth: 1
@@ -109,8 +105,8 @@
.. cpp:function:: Status hdlc_lite::WriteInformationFrame(uint8_t address, ConstByteSpan data, stream::Writer& writer)
- Writes a span of data to a :ref:`pw::stream::Writer <chapter-pw-stream>` and
- returns the status. This implementation uses the :ref:`chapter-pw-checksum`
+ Writes a span of data to a :ref:`pw::stream::Writer <module-pw_stream>` and
+ returns the status. This implementation uses the :ref:`module-pw_checksum`
module to compute the CRC-32 frame check sequence.
.. code-block:: cpp
diff --git a/pw_hdlc_lite/rpc_example/docs.rst b/pw_hdlc_lite/rpc_example/docs.rst
index 94bc3f6..492ec0e 100644
--- a/pw_hdlc_lite/rpc_example/docs.rst
+++ b/pw_hdlc_lite/rpc_example/docs.rst
@@ -1,19 +1,15 @@
-.. default-domain:: cpp
-
-.. highlight:: sh
-
-.. _chapter-pw-hdlc-rpc-example:
+.. _module-pw_hdlc_lite-rpc-example:
=============================
RPC over HDLC example project
=============================
-The :ref:`chapter-pw-hdlc-lite` module includes an example of bringing up a
-:ref:`chapter-pw-rpc` server that can be used to invoke RPCs. The example code
+The :ref:`module-pw_hdlc_lite` module includes an example of bringing up a
+:ref:`module-pw_rpc` server that can be used to invoke RPCs. The example code
is located at ``pw_hdlc_lite/rpc_example``. This section walks through invoking
RPCs interactively and with a script using the RPC over HDLC example.
These instructions assume the STM32F429i Discovery board, but they work with
-any target with :ref:`pw::sys_io <chapter-pw-sys-io>` implemented.
+any target with :ref:`pw::sys_io <module-pw_sys_io>` implemented.
---------------------
Getting started guide
diff --git a/pw_hex_dump/docs.rst b/pw_hex_dump/docs.rst
index e198d45..60d5044 100644
--- a/pw_hex_dump/docs.rst
+++ b/pw_hex_dump/docs.rst
@@ -1,8 +1,4 @@
-.. _chapter-pw-hex-dump:
-
-.. default-domain:: cpp
-
-.. highlight:: sh
+.. _module-pw_hex_dump:
-----------
pw_hex_dump
@@ -111,4 +107,4 @@
============
* pw_bytes
* pw_span
-* pw_status
\ No newline at end of file
+* pw_status
diff --git a/pw_kvs/docs.rst b/pw_kvs/docs.rst
index eea1073..0d9d402 100644
--- a/pw_kvs/docs.rst
+++ b/pw_kvs/docs.rst
@@ -1,8 +1,4 @@
-.. _chapter-pw-kvs:
-
-.. default-domain:: cpp
-
-.. highlight:: cpp
+.. _module-pw_kvs:
------
pw_kvs
diff --git a/pw_log/docs.rst b/pw_log/docs.rst
index c232139..8f5c31e 100644
--- a/pw_log/docs.rst
+++ b/pw_log/docs.rst
@@ -1,8 +1,4 @@
-.. _chapter-pw-log:
-
-.. default-domain:: cpp
-
-.. highlight:: cpp
+.. _module-pw_log:
------
pw_log
@@ -328,9 +324,9 @@
porting server code to microcontrollers quickly, we do not advise embedded
projects use that approach unless absolutely necessary.
-- See also :ref:`chapter-pw-log-tokenized` for details on leveraging Pigweed's
+- See also :ref:`module-pw_log_tokenized` for details on leveraging Pigweed's
tokenizer module for logging.
-- See also :ref:`chapter-pw-tokenizer` for details on Pigweed's tokenizer,
+- See also :ref:`module-pw_tokenizer` for details on Pigweed's tokenizer,
which is useful for more than just logging.
Why does the facade use header redirection instead of C functions?
diff --git a/pw_log_basic/docs.rst b/pw_log_basic/docs.rst
index 330a4db..985ec50 100644
--- a/pw_log_basic/docs.rst
+++ b/pw_log_basic/docs.rst
@@ -1,8 +1,4 @@
-.. _chapter-pw-log-basic:
-
-.. default-domain:: cpp
-
-.. highlight:: sh
+.. _module-pw_log_basic:
------------
pw_log_basic
diff --git a/pw_log_null/docs.rst b/pw_log_null/docs.rst
index 6b80809..fa7466f 100644
--- a/pw_log_null/docs.rst
+++ b/pw_log_null/docs.rst
@@ -1,8 +1,4 @@
-.. _chapter-pw-log-null:
-
-.. default-domain:: cpp
-
-.. highlight:: sh
+.. _module-pw_log_null:
-----------
pw_log_null
@@ -18,6 +14,6 @@
.. tip::
If you are concerned about the resource demands of logging, try tokenizing
- logs with :ref:`chapter-pw-tokenizer` and :ref:`chapter-pw-log-tokenized`
+ logs with :ref:`module-pw_tokenizer` and :ref:`module-pw_log_tokenized`
instead of disabling logs completely. Tokenized logs provide exactly same
information as plain text logs but use dramatically less resources.
diff --git a/pw_log_rpc/docs.rst b/pw_log_rpc/docs.rst
index 914d3ac..ff8b466 100644
--- a/pw_log_rpc/docs.rst
+++ b/pw_log_rpc/docs.rst
@@ -1,8 +1,4 @@
-.. _chapter-pw-log-rpc:
-
-.. default-domain:: cpp
-
-.. highlight:: cpp
+.. _module-pw_log_rpc:
----------
pw_log_rpc
diff --git a/pw_log_tokenized/docs.rst b/pw_log_tokenized/docs.rst
index 1225006..323522f 100644
--- a/pw_log_tokenized/docs.rst
+++ b/pw_log_tokenized/docs.rst
@@ -1,8 +1,4 @@
-.. default-domain:: cpp
-
-.. highlight:: sh
-
-.. _chapter-pw-log-tokenized:
+.. _module-pw_log_tokenized:
----------------
pw_log_tokenized
diff --git a/pw_malloc/docs.rst b/pw_malloc/docs.rst
index 7d55265..d927d4c 100644
--- a/pw_malloc/docs.rst
+++ b/pw_malloc/docs.rst
@@ -1,6 +1,4 @@
-.. _chapter-pw-malloc:
-
-.. default-domain:: cpp
+.. _module-pw_malloc:
---------
pw_malloc
diff --git a/pw_malloc_freelist/docs.rst b/pw_malloc_freelist/docs.rst
index 928ac5b..c6483d2 100644
--- a/pw_malloc_freelist/docs.rst
+++ b/pw_malloc_freelist/docs.rst
@@ -1,6 +1,4 @@
-.. _chapter-pw-malloc-freelist:
-
-.. default-domain:: cpp
+.. _module-pw_malloc_freelist:
------------------
pw_malloc_freelist
diff --git a/pw_metric/docs.rst b/pw_metric/docs.rst
index 721883c..6bdcd5a 100644
--- a/pw_metric/docs.rst
+++ b/pw_metric/docs.rst
@@ -1,8 +1,4 @@
-.. _chapter-pw-metric:
-
-.. default-domain:: cpp
-
-.. highlight:: cpp
+.. _module-pw_metric:
=========
pw_metric
diff --git a/pw_minimal_cpp_stdlib/docs.rst b/pw_minimal_cpp_stdlib/docs.rst
index 8a574d3..29a89aa 100644
--- a/pw_minimal_cpp_stdlib/docs.rst
+++ b/pw_minimal_cpp_stdlib/docs.rst
@@ -1,6 +1,4 @@
-.. _chapter-pw-minimal-cpp-stdlib:
-
-.. default-domain:: cpp
+.. _module-pw_minimal_cpp_stdlib:
---------------------
pw_minimal_cpp_stdlib
diff --git a/pw_module/docs.rst b/pw_module/docs.rst
index 0eea2d0..ec564eb 100644
--- a/pw_module/docs.rst
+++ b/pw_module/docs.rst
@@ -1,20 +1,16 @@
-.. default-domain:: cpp
-
-.. highlight:: sh
-
-.. _chapter-module:
+.. _module-pw_module:
---------
pw_module
---------
The ``pw_module`` module contains tools for managing Pigweed modules.
For information on the structure of a Pigweed module, refer to
-:ref:`chapter-module-guide`
+:ref:`docs-module-guides`.
Commands
--------
-.. _chapter-module-module-check:
+.. _module-pw_module-module-check:
``pw module-check``
^^^^^^^^^^^^^^^^^^^
diff --git a/pw_polyfill/docs.rst b/pw_polyfill/docs.rst
index 25bcee0..1d35878 100644
--- a/pw_polyfill/docs.rst
+++ b/pw_polyfill/docs.rst
@@ -1,8 +1,4 @@
-.. _chapter-pw-polyfill:
-
-.. default-domain:: cpp
-
-.. highlight:: sh
+.. _module-pw_polyfill:
===========
pw_polyfill
diff --git a/pw_preprocessor/docs.rst b/pw_preprocessor/docs.rst
index 74345f1..9602a76 100644
--- a/pw_preprocessor/docs.rst
+++ b/pw_preprocessor/docs.rst
@@ -1,8 +1,4 @@
-.. _chapter-pw-preprocessor:
-
-.. default-domain:: cpp
-
-.. highlight:: sh
+.. _module-pw_preprocessor:
---------------
pw_preprocessor
diff --git a/pw_presubmit/docs.rst b/pw_presubmit/docs.rst
index 4be12a9..921cb35 100644
--- a/pw_presubmit/docs.rst
+++ b/pw_presubmit/docs.rst
@@ -1,8 +1,4 @@
-.. _chapter-pw-presubmit:
-
-.. default-domain:: cpp
-
-.. highlight:: sh
+.. _module-pw_presubmit:
============
pw_presubmit
@@ -53,7 +49,7 @@
Python script that uses the ``pw_presubmit`` package.
A project's presubmit script can be registered as a
-:ref:`pw_cli <chapter-pw-cli>` plugin, so that it can be run as ``pw
+:ref:`pw_cli <module-pw_cli>` plugin, so that it can be run as ``pw
presubmit``.
Setting up the command-line interface
diff --git a/pw_protobuf/decoding.rst b/pw_protobuf/decoding.rst
index d0dbea3..7120f60 100644
--- a/pw_protobuf/decoding.rst
+++ b/pw_protobuf/decoding.rst
@@ -1,8 +1,4 @@
-.. default-domain:: cpp
-
-.. highlight:: sh
-
-.. _chapter-protobuf-decoder:
+.. _module-pw_protobuf-decoding:
--------
Decoding
diff --git a/pw_protobuf/docs.rst b/pw_protobuf/docs.rst
index df6042c..ffc13bc 100644
--- a/pw_protobuf/docs.rst
+++ b/pw_protobuf/docs.rst
@@ -1,8 +1,4 @@
-.. default-domain:: cpp
-
-.. highlight:: sh
-
-.. _chapter-protobuf:
+.. _module-pw_protobuf:
-----------
pw_protobuf
@@ -36,7 +32,7 @@
``pw_protobuf`` splits wire format encoding and decoding operations. Links to
the design and APIs of each are listed in below.
-See also :ref:`chapter-pw-protobuf-compiler` for details on ``pw_protobuf``'s
+See also :ref:`module-pw_protobuf_compiler` for details on ``pw_protobuf``'s
build system integration.
**pw_protobuf functionality**
diff --git a/pw_protobuf_compiler/docs.rst b/pw_protobuf_compiler/docs.rst
index 4bb4cdc..9f04a26 100644
--- a/pw_protobuf_compiler/docs.rst
+++ b/pw_protobuf_compiler/docs.rst
@@ -1,8 +1,4 @@
-.. default-domain:: py
-
-.. highlight:: py
-
-.. _chapter-pw-protobuf-compiler:
+.. _module-pw_protobuf_compiler:
--------------------
pw_protobuf_compiler
diff --git a/pw_random/docs.rst b/pw_random/docs.rst
index f1455ea..fd4ba16 100644
--- a/pw_random/docs.rst
+++ b/pw_random/docs.rst
@@ -1,8 +1,4 @@
-.. _chapter-pw-random:
-
-.. default-domain:: cpp
-
-.. highlight:: sh
+.. _module-pw_random:
---------
pw_random
diff --git a/pw_result/docs.rst b/pw_result/docs.rst
index 02d6854..bfc37cd 100644
--- a/pw_result/docs.rst
+++ b/pw_result/docs.rst
@@ -1,8 +1,4 @@
-.. default-domain:: cpp
-
-.. highlight:: sh
-
-.. _chapter-pw-result:
+.. _module-pw_result:
---------
pw_result
diff --git a/pw_ring_buffer/docs.rst b/pw_ring_buffer/docs.rst
index c3ab200..2209468 100644
--- a/pw_ring_buffer/docs.rst
+++ b/pw_ring_buffer/docs.rst
@@ -1,6 +1,4 @@
-.. default-domain:: cpp
-
-.. highlight:: sh
+.. _module-pw_ring_buffer:
--------------
pw_ring_buffer
diff --git a/pw_rpc/docs.rst b/pw_rpc/docs.rst
index 048627f..6d235f0 100644
--- a/pw_rpc/docs.rst
+++ b/pw_rpc/docs.rst
@@ -1,8 +1,4 @@
-.. default-domain:: cpp
-
-.. highlight:: sh
-
-.. _chapter-pw-rpc:
+.. _module-pw_rpc:
------
pw_rpc
@@ -12,8 +8,9 @@
.. admonition:: Try it out!
- For a quick intro to ``pw_rpc``, see the :ref:`chapter-pw-hdlc-rpc-example` in
- the :ref:`chapter-pw-hdlc-lite` module.
+ For a quick intro to ``pw_rpc``, see the
+ :ref:`module-pw_hdlc_lite-rpc-example` in the :ref:`module-pw_hdlc_lite`
+ module.
.. attention::
@@ -116,8 +113,8 @@
3. Register the service with a server
-------------------------------------
-This example code sets up an RPC server with an
-:ref:`HDLC<chapter-pw-hdlc-lite>` channel output and the example service.
+This example code sets up an RPC server with an :ref:`HDLC<module-pw_hdlc_lite>`
+channel output and the example service.
.. code-block:: cpp
@@ -164,7 +161,7 @@
``pw_rpc`` supports multiple protobuf libraries, and the generated code API
depends on which is used.
-.. _pw-rpc-protobuf-apis:
+.. _module-pw_rpc-protobuf-library-apis:
Protobuf library APIs
=====================
@@ -717,9 +714,10 @@
registered channels instead. A service client class is generated from a .proto
file for each selected protobuf library, which is then used to send RPC requests
through a given channel. The API for this depends on the protobuf library;
-please refer to the :ref:`appropriate documentation <pw-rpc-protobuf-apis>`.
-Multiple service client implementations can exist simulatenously and share the
-same ``Client`` class.
+please refer to the
+:ref:`appropriate documentation<module-pw_rpc-protobuf-library-apis>`. Multiple
+service client implementations can exist simulatenously and share the same
+``Client`` class.
When a call is made, a ``pw::rpc::ClientCall`` object is returned to the caller.
This object tracks the ongoing RPC call, and can be used to manage it. An RPC
diff --git a/pw_rpc/nanopb/docs.rst b/pw_rpc/nanopb/docs.rst
index 9ac3ab9..b1b6b9f 100644
--- a/pw_rpc/nanopb/docs.rst
+++ b/pw_rpc/nanopb/docs.rst
@@ -1,8 +1,4 @@
-.. default-domain:: cpp
-
-.. highlight:: sh
-
-.. _chapter-pw-rpc-nanopb:
+.. _module-pw_rpc_nanopb:
------
nanopb
@@ -14,7 +10,7 @@
=====
To enable nanopb code generation, add ``nanopb_rpc`` as a generator to your
Pigweed target's ``pw_protobuf_GENERATORS`` list. Refer to
-:ref:`chapter-pw-protobuf-compiler` for additional information.
+:ref:`module-pw_protobuf_compiler` for additional information.
.. code::
diff --git a/pw_span/docs.rst b/pw_span/docs.rst
index 64dad43..2987ce4 100644
--- a/pw_span/docs.rst
+++ b/pw_span/docs.rst
@@ -1,8 +1,4 @@
-.. _chapter-pw-span:
-
-.. default-domain:: cpp
-
-.. highlight:: sh
+.. _module-pw_span:
-------
pw_span
diff --git a/pw_status/docs.rst b/pw_status/docs.rst
index 465c3d0..a2de75f 100644
--- a/pw_status/docs.rst
+++ b/pw_status/docs.rst
@@ -1,8 +1,4 @@
-.. _chapter-pw-status:
-
-.. default-domain:: cpp
-
-.. highlight:: sh
+.. _module-pw_status:
---------
pw_status
diff --git a/pw_stream/docs.rst b/pw_stream/docs.rst
index b1edfa0..2fcd644 100644
--- a/pw_stream/docs.rst
+++ b/pw_stream/docs.rst
@@ -1,8 +1,4 @@
-.. default-domain:: cpp
-
-.. highlight:: sh
-
-.. _chapter-pw-stream:
+.. _module-pw_stream:
---------
pw_stream
diff --git a/pw_string/docs.rst b/pw_string/docs.rst
index 37df397..8944100 100644
--- a/pw_string/docs.rst
+++ b/pw_string/docs.rst
@@ -1,8 +1,4 @@
-.. _chapter-pw-string:
-
-.. default-domain:: cpp
-
-.. highlight:: sh
+.. _module-pw_string:
---------
pw_string
diff --git a/pw_sys_io/docs.rst b/pw_sys_io/docs.rst
index c87e0ac..cde6a3c 100644
--- a/pw_sys_io/docs.rst
+++ b/pw_sys_io/docs.rst
@@ -1,8 +1,4 @@
-.. _chapter-pw-sys-io:
-
-.. default-domain:: cpp
-
-.. highlight:: sh
+.. _module-pw_sys_io:
---------
pw_sys_io
diff --git a/pw_sys_io_arduino/docs.rst b/pw_sys_io_arduino/docs.rst
index 992ae53..79c533d 100644
--- a/pw_sys_io_arduino/docs.rst
+++ b/pw_sys_io_arduino/docs.rst
@@ -1,8 +1,4 @@
-.. default-domain:: cpp
-
-.. highlight:: sh
-
-.. _chapter-pw-sys-io-arduino:
+.. _module-pw_sys_io_arduino:
-----------------
pw_sys_io_arduino
@@ -26,6 +22,6 @@
serial port.
.. seealso::
- - :ref:`chapter-arduino` target documentation for a list of working hardware.
- - :ref:`chapter-pw-arduino-build` for caveats when running Pigweed on top of
+ - :ref:`target-arduino` target documentation for a list of working hardware.
+ - :ref:`module-pw_arduino_build` for caveats when running Pigweed on top of
the Arduino API.
diff --git a/pw_sys_io_baremetal_stm32f429/docs.rst b/pw_sys_io_baremetal_stm32f429/docs.rst
index 44c68e3..1f1fe08 100644
--- a/pw_sys_io_baremetal_stm32f429/docs.rst
+++ b/pw_sys_io_baremetal_stm32f429/docs.rst
@@ -1,8 +1,4 @@
-.. _chapter-pw-sys-io-baremetal-stm32f429:
-
-.. default-domain:: cpp
-
-.. highlight:: sh
+.. _module-pw_sys_io_baremetal_stm32f429:
-----------------------------
pw_sys_io_baremetal_stm32f429
diff --git a/pw_sys_io_stdio/docs.rst b/pw_sys_io_stdio/docs.rst
index 31a9357..7280656 100644
--- a/pw_sys_io_stdio/docs.rst
+++ b/pw_sys_io_stdio/docs.rst
@@ -1,8 +1,4 @@
-.. _chapter-pw-sys-io-stdio:
-
-.. default-domain:: cpp
-
-.. highlight:: sh
+.. _module-pw_sys_io_stdio:
---------------
pw_sys_io_stdio
diff --git a/pw_target_runner/docs.rst b/pw_target_runner/docs.rst
index 9306692..bca7084 100644
--- a/pw_target_runner/docs.rst
+++ b/pw_target_runner/docs.rst
@@ -1,8 +1,4 @@
-.. default-domain:: cpp
-
-.. highlight:: sh
-
-.. _chapter-pw-target-runner:
+.. _module-pw_target_runner:
----------------
pw_target_runner
diff --git a/pw_target_runner/go/docs.rst b/pw_target_runner/go/docs.rst
index 3c1abb7..6303237 100644
--- a/pw_target_runner/go/docs.rst
+++ b/pw_target_runner/go/docs.rst
@@ -1,8 +1,4 @@
-.. _chapter-test-server:
-
-.. default-domain:: go
-
-.. highlight:: go
+.. _module-pw_target_runner-go:
--
Go
@@ -21,7 +17,7 @@
The code below implements a very basic test server with two test workers which
print out the path of the tests they are scheduled to run.
-.. code::
+.. code-block:: go
package main
diff --git a/pw_tokenizer/docs.rst b/pw_tokenizer/docs.rst
index 2d6ffe4..bff0fe1 100644
--- a/pw_tokenizer/docs.rst
+++ b/pw_tokenizer/docs.rst
@@ -1,8 +1,4 @@
-.. default-domain:: cpp
-
-.. highlight:: sh
-
-.. _chapter-pw-tokenizer:
+.. _module-pw_tokenizer:
------------
pw_tokenizer
diff --git a/pw_toolchain/docs.rst b/pw_toolchain/docs.rst
index 68706a5..07e27fb 100644
--- a/pw_toolchain/docs.rst
+++ b/pw_toolchain/docs.rst
@@ -1,8 +1,4 @@
-.. _chapter-pw-toolchain:
-
-.. default-domain:: cpp
-
-.. highlight:: cpp
+.. _module-pw_toolchain:
------------
pw_toolchain
diff --git a/pw_trace/docs.rst b/pw_trace/docs.rst
index 37e7d89..60aa359 100644
--- a/pw_trace/docs.rst
+++ b/pw_trace/docs.rst
@@ -1,8 +1,4 @@
-.. _chapter-pw-trace:
-
-.. default-domain:: cpp
-
-.. highlight:: cpp
+.. _module-pw_trace:
========
pw_trace
diff --git a/pw_trace_tokenized/docs.rst b/pw_trace_tokenized/docs.rst
index 6548a03..c1c27ac 100644
--- a/pw_trace_tokenized/docs.rst
+++ b/pw_trace_tokenized/docs.rst
@@ -1,8 +1,4 @@
-.. _chapter-pw-trace_tokenized:
-
-.. default-domain:: cpp
-
-.. highlight:: cpp
+.. _module-pw_trace_tokenized:
==================
pw_trace_tokenized
diff --git a/pw_unit_test/docs.rst b/pw_unit_test/docs.rst
index 34c7d57..5bec124 100644
--- a/pw_unit_test/docs.rst
+++ b/pw_unit_test/docs.rst
@@ -1,8 +1,4 @@
-.. default-domain:: cpp
-
-.. highlight:: sh
-
-.. _chapter-pw-unit-test:
+.. _module-pw_unit_test:
------------
pw_unit_test
diff --git a/pw_varint/docs.rst b/pw_varint/docs.rst
index 49db88e..3327ccd 100644
--- a/pw_varint/docs.rst
+++ b/pw_varint/docs.rst
@@ -1,6 +1,4 @@
-.. default-domain:: cpp
-
-.. highlight:: sh
+.. _module-pw_varint:
---------
pw_varint
diff --git a/pw_watch/docs.rst b/pw_watch/docs.rst
index df6c059..9b8ee45 100644
--- a/pw_watch/docs.rst
+++ b/pw_watch/docs.rst
@@ -1,8 +1,4 @@
-.. default-domain:: python
-
-.. highlight:: sh
-
-.. _chapter-pw-watch:
+.. _module-pw_watch:
--------
pw_watch
@@ -64,4 +60,4 @@
affected by a file change are run when ``pw_watch`` triggers a build. By
default, host builds using ``pw_watch`` will run unit tests. To run unit tests
on a device as part of ``pw_watch``, refer to your device's
-:ref:`target documentation<chapter-targets>`.
+:ref:`target documentation<docs-targets>`.
diff --git a/pw_web_ui/docs.rst b/pw_web_ui/docs.rst
index 05ca8c5..18d5f21 100644
--- a/pw_web_ui/docs.rst
+++ b/pw_web_ui/docs.rst
@@ -1,14 +1,11 @@
-.. _chapter-pw-web-ui:
+.. _module-pw_web_ui:
-.. default-domain:: **js**
-
------------
+---------
pw_web_ui
------------
+---------
This module is a set of npm libraries for building web UIs
for pigweed devices.
Note that this module and its documentation are currently incomplete and
experimental.
-
diff --git a/targets/arduino/target_docs.rst b/targets/arduino/target_docs.rst
index cdddf44..a583539 100644
--- a/targets/arduino/target_docs.rst
+++ b/targets/arduino/target_docs.rst
@@ -1,8 +1,4 @@
-.. default-domain:: cpp
-
-.. highlight:: sh
-
-.. _chapter-arduino:
+.. _target-arduino:
-------
Arduino
@@ -12,7 +8,7 @@
.. seealso::
There are a few caveats when running Pigweed on top of the Arduino API. See
- :ref:`chapter-pw-arduino-build` for details.
+ :ref:`module-pw_arduino_build` for details.
Supported Boards
================
diff --git a/targets/docs/target_docs.rst b/targets/docs/target_docs.rst
index 4c7601a..37db6c2 100644
--- a/targets/docs/target_docs.rst
+++ b/targets/docs/target_docs.rst
@@ -1,8 +1,4 @@
-.. _chapter-docs:
-
-.. default-domain:: cpp
-
-.. highlight:: sh
+.. _target-docs:
----
docs
diff --git a/targets/host/target_docs.rst b/targets/host/target_docs.rst
index bf83926..de087a1 100644
--- a/targets/host/target_docs.rst
+++ b/targets/host/target_docs.rst
@@ -1,8 +1,4 @@
-.. _chapter-host:
-
-.. default-domain:: cpp
-
-.. highlight:: sh
+.. _target-host:
----
host
diff --git a/targets/lm3s6965evb-qemu/target_docs.rst b/targets/lm3s6965evb-qemu/target_docs.rst
index 0b95d89..6e8c12f 100644
--- a/targets/lm3s6965evb-qemu/target_docs.rst
+++ b/targets/lm3s6965evb-qemu/target_docs.rst
@@ -1,8 +1,4 @@
-.. _chapter-lm3s6965evb-qemu:
-
-.. default-domain:: cpp
-
-.. highlight:: sh
+.. _target-lm3s6965evb-qemu:
----------------
lm3s6965evb-qemu
diff --git a/targets/stm32f429i-disc1/target_docs.rst b/targets/stm32f429i-disc1/target_docs.rst
index 5778460..68e34d8 100644
--- a/targets/stm32f429i-disc1/target_docs.rst
+++ b/targets/stm32f429i-disc1/target_docs.rst
@@ -1,8 +1,4 @@
-.. _chapter-stm32f429i-disc1:
-
-.. default-domain:: cpp
-
-.. highlight:: sh
+.. _target-stm32f429i-disc1:
----------------
stm32f429i-disc1
