pw_docgen: Add bug Docutils role

This is intended to simplify generating bug references.

Implementation based on the example in
https://docutils.sourceforge.io/docs/howto/rst-roles.html#rfc-reference-role.

Test: Reviewed the generated documentation and clicked on the links.
Change-Id: Id0c22196a3ec4718b4ef748b4240107bebf8ae40
Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/215911
Reviewed-by: Kayce Basques <kayce@google.com>
Commit-Queue: Ted Pudlik <tpudlik@google.com>
Lint: Lint 🤖 <android-build-ayeaye@system.gserviceaccount.com>

docs/automated_analysis.rst

@@ -106,7 +106,7 @@ described in this section. For more detail about these sanitizers, see the
 
 .. note::
    Pigweed does not currently support `MemorySanitizer`_ (msan). See
-   https://pwbug.dev/234876100 for details.
+   :bug:`234876100` for details.
 
 The exact configurations we use for these sanitizers are in
 `pw_toolchain/host_clang/BUILD.gn <https://cs.pigweed.dev/pigweed/+/main:pw_toolchain/host_clang/BUILD.gn>`_.

docs/blog/02-bazel-feature-flags.rst

@@ -609,8 +609,7 @@ widely"? Well we can. So that's the doc you're reading now!
 
 But arguably the story shouldn't end here: Pigweed should probably provide a
 ready-made implementation of Chromium build flags for downstream projects. See
-`issue #342454993 <https://pwbug.dev/342454993>`_ to check out how that's
+:bug:`342454993` to check out how that's going!
-going!
 
 Do you need to generate actual files?
 =====================================

docs/conf.py

@@ -40,6 +40,7 @@ pygments_style = 'pw_console.pigweed_code_style.PigweedCodeLightStyle'
 pygments_dark_style = 'pw_console.pigweed_code_style.PigweedCodeStyle'
 
 extensions = [
+    "pw_docgen.sphinx.bug",
     "pw_docgen.sphinx.google_analytics",  # Enables optional Google Analytics
     "pw_docgen.sphinx.kconfig",
     "pw_docgen.sphinx.module_metadata",

docs/get_started/bazel_integration.rst

@@ -40,7 +40,7 @@ We don't yet publish releases that could be pulled in using `http_archive
 <https://bazel.build/rules/lib/repo/http#http_archive>`__.
 
 We don't support `bzlmod <https://bazel.build/external/overview#bzlmod>`__ yet.
-See http://pwbug.dev/258836641.
+See :bug:`258836641`.
 
 If either of these limitations is important to you, please reach out to us on
 `chat <https://discord.gg/M9NSeTA>`__.

docs/style/cli.rst

@@ -27,8 +27,7 @@ The following programs demonstrate conformance to Pigweed's CLI style guide rule
 * `pw_digital_io_linux_cli
   <https://cs.opensource.google/pigweed/pigweed/+/main:pw_digital_io_linux/digital_io_cli.cc>`_
 
-  * Note: This does not yet fully conform. See issue `#330435501
+  * Note: This does not yet fully conform. See :bug:`330435501`.
-    <https://pwbug.dev/330435501>`_.
 
 ----------
 Exit codes
@@ -138,8 +137,7 @@ conditions.
 .. warning::
 
    Currently there is no preconfigured ``pw_log`` backend which sends log
-   messages to ``stderr``.
+   messages to ``stderr``.  See :bug:`329747262`.
-   See issue `#329747262 <https://pwbug.dev/329747262>`_.
 
    This can be achieved by using ``pw_log_basic`` and calling ``SetOutput()``
    as follows:
@@ -153,8 +151,7 @@ conditions.
 .. warning::
 
    Currently there is no mechanism for setting the ``pw_log`` level at runtime.
-   (E.g. via ``--verbose`` or ``--quiet`` options).
+   (E.g. via ``--verbose`` or ``--quiet`` options).  See :bug:`329755001`.
-   See issue `#329755001 <https://pwbug.dev/329755001>`_.
 
 **Exceptions**:
 

pw_bluetooth/docs.rst

@@ -196,7 +196,7 @@ Delta of +96 when adding a second packet view and reading/writing a field.
 Roadmap
 -------
 - Bluetooth Proxy (WIP in in :ref:`module-pw_bluetooth_proxy`)
-- Add automated Emboss file formatting to `pw format` (`b/331195584 <https://pwbug.dev/331195584>`_)
+- Add automated Emboss file formatting to `pw format` (:bug:`331195584`)
 - Create a backend for the Bluetooth API using Fuchsia's Bluetooth stack
   (Sapphire).
 - Stabilize the Bluetooth API.

pw_docgen/docs.rst

@@ -220,7 +220,20 @@ upstream Pigweed repo:
 
    grep '<link rel="canonical' out/docs/gen/docs/html/* -R
 
-Context: `b/323077749 <https://issues.pigweed.dev/323077749>`_
+Context: :bug:`323077749`.
+
+bug
+---
+This extension simplifies adding references to issues (bugs) in the Pigweed
+issue tracker. It defines a `Docutils role
+<https://docutils.sourceforge.io/docs/ref/rst/roles.html>`__ that can be
+used as follows.
+
+.. code-block:: rst
+
+   For more details see :bug:`323077749`.
+
+This becomes a hyperlink to https://pwbug.dev/323077749.
 
 google_analytics
 ----------------

pw_docgen/py/BUILD.gn

@@ -27,6 +27,7 @@ pw_python_package("py") {
     "pw_docgen/docserver.py",
     "pw_docgen/seed.py",
     "pw_docgen/sphinx/__init__.py",
+    "pw_docgen/sphinx/bug.py",
     "pw_docgen/sphinx/google_analytics.py",
     "pw_docgen/sphinx/inlinesearch/__init__.py",
     "pw_docgen/sphinx/kconfig.py",

pw_docgen/py/pw_docgen/sphinx/bug.py

@@ -0,0 +1,55 @@
+# Copyright 2024 The Pigweed Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you may not
+# use this file except in compliance with the License. You may obtain a copy of
+# the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations under
+# the License.
+"""Custom role for creating bug links."""
+
+from docutils import nodes
+from docutils.parsers.rst import roles
+
+from sphinx.application import Sphinx
+
+
+def bug_role(
+    role,  # pylint: disable=unused-argument
+    rawtext,
+    text,
+    lineno,
+    inliner,
+    options=None,
+    content=None,  # pylint: disable=unused-argument
+):
+    options = roles.normalized_role_options(options)
+    try:
+        bug = int(nodes.unescape(text))
+        if bug < 1:
+            raise ValueError
+    except ValueError:
+        msg = inliner.reporter.error(
+            'Bug number must be a number greater than or equal to 1; '
+            '"%s" is invalid.' % text,
+            line=lineno,
+        )
+        prb = inliner.problematic(rawtext, rawtext, msg)
+        return [prb], [msg]
+
+    ref = 'https://pwbug.dev/{:d}'.format(bug)
+    node = nodes.reference(rawtext, 'b/{:d}'.format(bug), refuri=ref, **options)
+    return [node], []
+
+
+def setup(app: Sphinx) -> dict[str, bool]:
+    app.add_role('bug', bug_role)
+    return {
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }

pw_presubmit/format.rst

@@ -9,12 +9,12 @@ Code formatting
 .. admonition:: Note
    :class: warning
 
-   https://pwbug.dev/326309165: While the ``pw format`` command interface is
+   :bug:`326309165`: While the ``pw format`` command interface is very stable,
-   very stable, the ``pw_presubmit.format`` library is a work-in-progress
+   the ``pw_presubmit.format`` library is a work-in-progress effort to detach
-   effort to detach the implementation of ``pw format`` from
+   the implementation of ``pw format`` from the :ref:`module-pw_presubmit`
-   the :ref:`module-pw_presubmit` module. Not all formatters are migrated, and
+   module. Not all formatters are migrated, and the library API is unstable.
-   the library API is unstable. After some of the core pieces land, this
+   After some of the core pieces land, this library will be moved to
-   library will be moved to ``pw_code_format``.
+   ``pw_code_format``.
 
 .. _module-pw_presubmit-format-api: