From 42504afa03234e3276471f16d4f23ce571c38ccd Mon Sep 17 00:00:00 2001 From: Ted Pudlik Date: Tue, 18 Jun 2024 17:40:46 +0000 Subject: [PATCH] pw_docgen: Add bug Docutils role MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Commit-Queue: Ted Pudlik Lint: Lint 🤖 --- docs/automated_analysis.rst | 2 +- docs/blog/02-bazel-feature-flags.rst | 3 +- docs/conf.py | 1 + docs/get_started/bazel_integration.rst | 2 +- docs/style/cli.rst | 9 ++--- pw_bluetooth/docs.rst | 2 +- pw_docgen/docs.rst | 15 ++++++- pw_docgen/py/BUILD.gn | 1 + pw_docgen/py/pw_docgen/sphinx/bug.py | 55 ++++++++++++++++++++++++++ pw_presubmit/format.rst | 12 +++--- 10 files changed, 84 insertions(+), 18 deletions(-) create mode 100644 pw_docgen/py/pw_docgen/sphinx/bug.py diff --git a/docs/automated_analysis.rst b/docs/automated_analysis.rst index 2e465a6b1..2292b5120 100644 --- a/docs/automated_analysis.rst +++ b/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 `_. diff --git a/docs/blog/02-bazel-feature-flags.rst b/docs/blog/02-bazel-feature-flags.rst index 2b8118628..122efeea9 100644 --- a/docs/blog/02-bazel-feature-flags.rst +++ b/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 `_ to check out how that's -going! +:bug:`342454993` to check out how that's going! Do you need to generate actual files? ===================================== diff --git a/docs/conf.py b/docs/conf.py index ad3b06521..0e900bbf8 100644 --- a/docs/conf.py +++ b/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", diff --git a/docs/get_started/bazel_integration.rst b/docs/get_started/bazel_integration.rst index 352457ed2..554c1e63b 100644 --- a/docs/get_started/bazel_integration.rst +++ b/docs/get_started/bazel_integration.rst @@ -40,7 +40,7 @@ We don't yet publish releases that could be pulled in using `http_archive `__. We don't support `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 `__. diff --git a/docs/style/cli.rst b/docs/style/cli.rst index 498cf7cbf..bbe69e810 100644 --- a/docs/style/cli.rst +++ b/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 `_ - * Note: This does not yet fully conform. See issue `#330435501 - `_. + * Note: This does not yet fully conform. See :bug:`330435501`. ---------- Exit codes @@ -138,8 +137,7 @@ conditions. .. warning:: Currently there is no preconfigured ``pw_log`` backend which sends log - messages to ``stderr``. - See issue `#329747262 `_. + messages to ``stderr``. See :bug:`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). - See issue `#329755001 `_. + (E.g. via ``--verbose`` or ``--quiet`` options). See :bug:`329755001`. **Exceptions**: diff --git a/pw_bluetooth/docs.rst b/pw_bluetooth/docs.rst index c8839788e..3dce2d91a 100644 --- a/pw_bluetooth/docs.rst +++ b/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 `_) +- 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. diff --git a/pw_docgen/docs.rst b/pw_docgen/docs.rst index 5f01e974a..12c638f0c 100644 --- a/pw_docgen/docs.rst +++ b/pw_docgen/docs.rst @@ -220,7 +220,20 @@ upstream Pigweed repo: grep ' dict[str, bool]: + app.add_role('bug', bug_role) + return { + 'parallel_read_safe': True, + 'parallel_write_safe': True, + } diff --git a/pw_presubmit/format.rst b/pw_presubmit/format.rst index 643425c35..efc5480f5 100644 --- a/pw_presubmit/format.rst +++ b/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 - very stable, the ``pw_presubmit.format`` library is a work-in-progress - effort to detach the implementation of ``pw format`` from - the :ref:`module-pw_presubmit` module. Not all formatters are migrated, and - the library API is unstable. After some of the core pieces land, this - library will be moved to ``pw_code_format``. + :bug:`326309165`: While the ``pw format`` command interface is very stable, + the ``pw_presubmit.format`` library is a work-in-progress effort to detach + the implementation of ``pw format`` from the :ref:`module-pw_presubmit` + module. Not all formatters are migrated, and the library API is unstable. + After some of the core pieces land, this library will be moved to + ``pw_code_format``. .. _module-pw_presubmit-format-api: