docs: Prepend module name in HTML title node

When viewing the API reference for pw_string the browser tab title only says "API reference - Pigweed". This change prepends the module name in the title (e.g. "pw_string: API reference - Pigweed") to make the titles more usable. Some older docs explicitly reference the module name in their docs titles. This is no longer necessary. Bug: 380437250 Change-Id: I552ebd4470791a51aad036b53578189ef3c0ec30 Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/259512 Pigweed-Auto-Submit: Kayce Basques <[email protected]> Commit-Queue: Auto-Submit <[email protected]> Lint: Lint 🤖 <[email protected]> Commit-Queue: Kayce Basques <[email protected]> Presubmit-Verified: CQ Bot Account <[email protected]> Reviewed-by: Chad Norvell <[email protected]>
google · Jan 11, 2025 · 7e574a5 · 7e574a5
1 parent 68cebbd
commit 7e574a5
Show file tree

Hide file tree

Showing 53 changed files with 144 additions and 119 deletions.
diff --git a/docs/layout/layout.html b/docs/layout/layout.html
@@ -16,11 +16,36 @@
 
 {% extends "pydata_sphinx_theme/layout.html" %}
 
+{# htmltitle controls the HTML title node. On some pages we customize
+   the title to make it more usable. #}
+{% block htmltitle %}
+  {# Override the title for some module pages. #}
+  {% if pagename.startswith('pw_') %}
+    {% set tokens = pagename.split('/') %}
+    {% set module_name = tokens[0] %}
+    {% set maybe_doc_name = tokens[1] %}
+    {% if maybe_doc_name == 'docs' %}
+      {# It's the homepage for a module. Use the normal title. #}
+      <title>{{ title|striptags|e }}{{ titlesuffix }}</title>
+    {% else %}
+      {# It's a subpage of the module's docs, e.g. the API reference.
+         Prepend the module's name so that it's easier to see what module
+         this doc is related to. E.g. before our change the default title
+         just says "API reference - Pigweed" and after our change it says
+         "pw_string: API reference - Pigweed". #}
+      <title>{{ module_name }}: {{ title|striptags|e }}{{ titlesuffix }}</title>
+    {% endif %}
+  {# It's a non-module page. Use the normal title. #}
+  {% else %}
+    <title>{{ title|striptags|e }}{{ titlesuffix }}</title>
+  {% endif %}
+{% endblock %}
+
 {% block extrahead %}
+  {{ super() }}
   <!-- Preconnect with Google Fonts to speed up font loading. -->
   <link rel="preconnect" href="https://fonts.googleapis.com">
   <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
-  {{ super() }}
   {% if pagename == 'search' %}
     {# Search tools are already loaded on search page. Don't load them twice. #}
   {% else %}

diff --git a/pw_assert/backends.rst b/pw_assert/backends.rst
@@ -1,8 +1,8 @@
 .. _module-pw_assert-backends:
 
-==================
-pw_assert backends
-==================
+========
+Backends
+========
 .. pigweed-module-subpage::
    :name: pw_assert
 

diff --git a/pw_assert/docs.rst b/pw_assert/docs.rst
@@ -886,4 +886,4 @@ Missing Functionality
 .. toctree::
    :maxdepth: 1
 
-   Backends <backends>
+   backends
diff --git a/pw_async/backends.rst b/pw_async/backends.rst
@@ -1,8 +1,8 @@
 .. _module-pw_async-backends:
 
-=================
-pw_async backends
-=================
+========
+Backends
+========
 .. pigweed-module-subpage::
    :name: pw_async
 

diff --git a/pw_async/docs.rst b/pw_async/docs.rst
@@ -208,4 +208,4 @@ Roadmap
    :hidden:
    :maxdepth: 1
 
-   Backends <backends>
+   backends
diff --git a/pw_async2/backends.rst b/pw_async2/backends.rst
@@ -1,8 +1,8 @@
 .. _module-pw_async2-backends:
 
-==================
-pw_async2 backends
-==================
+========
+Backends
+========
 The :ref:`pw_async2 interface <module-pw_async2-reference>` must be fulfilled
 by a concrete implementation. You can use one of the Pigweed-provided backends
 listed below or roll your own. If you roll your own, please consider

diff --git a/pw_async2/docs.rst b/pw_async2/docs.rst
@@ -99,4 +99,4 @@ Tasks can then be run on a :cpp:class:`pw::async2::Dispatcher` using the
 
    guides
    reference
-   Backends <backends>
+   backends
diff --git a/pw_boot/backends.rst b/pw_boot/backends.rst
@@ -1,8 +1,8 @@
 .. _module-pw_boot-backends:
 
-==================
-pw_boot backends
-==================
+========
+Backends
+========
 .. TODO: b/323607687 - Add backend guidance here
 
 .. toctree::

diff --git a/pw_boot/docs.rst b/pw_boot/docs.rst
@@ -158,4 +158,4 @@ Dependencies
    :hidden:
    :maxdepth: 1
 
-   Backends <backends>
+   backends
diff --git a/pw_chrono/backends.rst b/pw_chrono/backends.rst
@@ -1,8 +1,8 @@
 .. _module-pw_chrono-backends:
 
-==================
-pw_chrono backends
-==================
+========
+Backends
+========
 .. pigweed-module-subpage::
    :name: pw_chrono
 

diff --git a/pw_chrono/docs.rst b/pw_chrono/docs.rst
@@ -617,4 +617,4 @@ being close to actual time, but do care that it increments like a real clock.
    :hidden:
    :maxdepth: 1
 
-   Backends <backends>
+   backends
diff --git a/pw_cpu_exception/backends.rst b/pw_cpu_exception/backends.rst
@@ -1,8 +1,8 @@
 .. _module-pw_cpu_exception-backends:
 
-=========================
-pw_cpu_exception backends
-=========================
+========
+Backends
+========
 .. TODO: b/323607687 - Add backend guidance here
 
 .. toctree::

diff --git a/pw_cpu_exception/docs.rst b/pw_cpu_exception/docs.rst
@@ -148,4 +148,4 @@ Dependencies
    :hidden:
    :maxdepth: 1
 
-   Backends <backends>
+   backends
diff --git a/pw_digital_io/backends.rst b/pw_digital_io/backends.rst
@@ -1,8 +1,8 @@
 .. _module-pw_digital_io-backends:
 
-======================
-pw_digital_io backends
-======================
+========
+Backends
+========
 .. TODO: b/323607687 - Add backend guidance here
 
 .. toctree::

diff --git a/pw_digital_io/docs.rst b/pw_digital_io/docs.rst
@@ -333,4 +333,4 @@ the project's configuration.
    :hidden:
    :maxdepth: 1
 
-   Backends <backends>
+   backends
diff --git a/pw_fuzzer/concepts.rst b/pw_fuzzer/concepts.rst
@@ -1,8 +1,8 @@
 .. _module-pw_fuzzer-concepts:
 
-===================
-pw_fuzzer: Concepts
-===================
+========
+Concepts
+========
 .. pigweed-module-subpage::
    :name: pw_fuzzer
 

diff --git a/pw_fuzzer/guides/fuzztest.rst b/pw_fuzzer/guides/fuzztest.rst
@@ -1,8 +1,8 @@
 .. _module-pw_fuzzer-guides-using_fuzztest:
 
-========================================
-pw_fuzzer: Adding Fuzzers Using FuzzTest
-========================================
+=============================
+Adding Fuzzers Using FuzzTest
+=============================
 .. pigweed-module-subpage::
    :name: pw_fuzzer
 

diff --git a/pw_fuzzer/guides/index.rst b/pw_fuzzer/guides/index.rst
@@ -4,9 +4,9 @@
 
 .. _module-pw_fuzzer-guides:
 
-=================
-pw_fuzzer: Guides
-=================
+======
+Guides
+======
 .. pigweed-module-subpage::
    :name: pw_fuzzer
 

diff --git a/pw_fuzzer/guides/libfuzzer.rst b/pw_fuzzer/guides/libfuzzer.rst
@@ -1,8 +1,8 @@
 .. _module-pw_fuzzer-guides-using_libfuzzer:
 
-=========================================
-pw_fuzzer: Adding Fuzzers Using LibFuzzer
-=========================================
+==============================
+Adding Fuzzers Using LibFuzzer
+==============================
 .. pigweed-module-subpage::
    :name: pw_fuzzer
 

diff --git a/pw_fuzzer/guides/reproducing_oss_fuzz_bugs.rst b/pw_fuzzer/guides/reproducing_oss_fuzz_bugs.rst
@@ -1,8 +1,8 @@
 .. _module-pw_fuzzer-guides-reproducing_oss_fuzz_bugs:
 
-=============================================
-pw_fuzzer: Using OSS-Fuzz
-=============================================
+==============
+Using OSS-Fuzz
+==============
 .. pigweed-module-subpage::
    :name: pw_fuzzer
 

diff --git a/pw_interrupt/backends.rst b/pw_interrupt/backends.rst
@@ -1,8 +1,8 @@
 .. _module-pw_interrupt-backends:
 
-=====================
-pw_interrupt backends
-=====================
+========
+Backends
+========
 .. TODO: b/323607687 - Add backend guidance here
 
 .. toctree::

diff --git a/pw_interrupt/docs.rst b/pw_interrupt/docs.rst
@@ -14,4 +14,4 @@ or not.
    :hidden:
    :maxdepth: 1
 
-   Backends <backends>
+   backends
diff --git a/pw_log/backends.rst b/pw_log/backends.rst
@@ -1,8 +1,8 @@
 .. _module-pw_log-backends:
 
-===============
-pw_log backends
-===============
+========
+Backends
+========
 .. pigweed-module-subpage::
    :name: pw_log
 

diff --git a/pw_log/docs.rst b/pw_log/docs.rst
@@ -508,4 +508,4 @@ pw_log.log_decoder
 
    protobuf
    tokenized_args
-   Backends <backends>
+   backends
diff --git a/pw_malloc/backends.rst b/pw_malloc/backends.rst
@@ -1,8 +1,8 @@
 .. _module-pw_malloc-backends:
 
-==================
-pw_malloc backends
-==================
+========
+Backends
+========
 .. pigweed-module-subpage::
    :name: pw_malloc
 

diff --git a/pw_malloc/docs.rst b/pw_malloc/docs.rst
@@ -79,4 +79,4 @@ If you configured a ``PW_MALLOC_METRICS_TYPE``, you can retrieve metrics using
    :maxdepth: 1
    :hidden:
 
-   Backends <backends>
+   backends
diff --git a/pw_protobuf/size_report.rst b/pw_protobuf/size_report.rst
@@ -1,8 +1,8 @@
 .. _module-pw_protobuf-size_report:
 
-================================
-pw_protobuf extended size report
-================================
+====================
+Extended size report
+====================
 .. pigweed-module-subpage::
    :name: pw_protobuf
 

diff --git a/pw_random/backends.rst b/pw_random/backends.rst
@@ -1,8 +1,8 @@
 .. _module-pw_random-backends:
 
-==================
-pw_random backends
-==================
+========
+Backends
+========
 .. pigweed-module-subpage::
    :name: pw_random
 

diff --git a/pw_random/docs.rst b/pw_random/docs.rst
@@ -55,4 +55,4 @@ random numbers are needed.
    :hidden:
    :maxdepth: 1
 
-   Backends <backends>
+   backends
diff --git a/pw_sensor/py/docs.rst b/pw_sensor/py/docs.rst
@@ -1,8 +1,8 @@
 .. _module-pw_sensor-py:
 
-========================
-pw_sensor Python package
-========================
+==============
+Python package
+==============
 .. pigweed-module::
    :name: pw_sensor
 

diff --git a/pw_software_update/cli.rst b/pw_software_update/cli.rst
@@ -1,8 +1,8 @@
 .. _module-pw_software_update-cli:
 
----------------------------------
-pw_software_update: CLI reference
----------------------------------
+-------------
+CLI reference
+-------------
 .. pigweed-module-subpage::
    :name: pw_software_update
 

diff --git a/pw_software_update/design.rst b/pw_software_update/design.rst
@@ -1,8 +1,8 @@
 .. _module-pw_software_update-design:
 
---------------------------
-pw_software_update: Design
---------------------------
+------
+Design
+------
 .. pigweed-module-subpage::
    :name: pw_software_update
 

diff --git a/pw_software_update/get_started.rst b/pw_software_update/get_started.rst
@@ -1,8 +1,8 @@
 .. _module-pw_software_update-get-started:
 
--------------------------------
-pw_software_update: Get started
--------------------------------
+-----------
+Get started
+-----------
 .. pigweed-module-subpage::
    :name: pw_software_update
 

diff --git a/pw_software_update/guides.rst b/pw_software_update/guides.rst
@@ -1,8 +1,8 @@
 .. _module-pw_software_update-guides:
 
--------------------------
-pw_software_update: Guide
--------------------------
+-----
+Guide
+-----
 .. pigweed-module-subpage::
    :name: pw_software_update
 

diff --git a/pw_spi/backends.rst b/pw_spi/backends.rst
@@ -1,8 +1,8 @@
 .. _module-pw_spi-backends:
 
-===============
-pw_spi backends
-===============
+========
+Backends
+========
 .. TODO: b/323607687 - Add backend guidance here
 
 .. toctree::

diff --git a/pw_spi/docs.rst b/pw_spi/docs.rst
@@ -368,4 +368,4 @@ protocols.
    :hidden:
    :maxdepth: 1
 
-   Backends <backends>
+   backends
diff --git a/pw_stream/backends.rst b/pw_stream/backends.rst
@@ -1,8 +1,8 @@
 .. _module-pw_stream-backends:
 
-==================
-pw_stream backends
-==================
+========
+Backends
+========
 .. TODO: b/323607687 - Add backend guidance here
 
 .. toctree::