mirror of
https://fuchsia.googlesource.com/third_party/pigweed.googlesource.com/pigweed/pigweed
synced 2024-07-12 01:23:34 +00:00
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>
This commit is contained in:
parent
3c319b21bb
commit
42504afa03
|
@ -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>`_.
|
||||
|
|
|
@ -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
|
||||
going!
|
||||
:bug:`342454993` to check out how that's going!
|
||||
|
||||
Do you need to generate actual files?
|
||||
=====================================
|
||||
|
|
|
@ -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",
|
||||
|
|
|
@ -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>`__.
|
||||
|
|
|
@ -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
|
||||
<https://pwbug.dev/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 <https://pwbug.dev/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 <https://pwbug.dev/329755001>`_.
|
||||
(E.g. via ``--verbose`` or ``--quiet`` options). See :bug:`329755001`.
|
||||
|
||||
**Exceptions**:
|
||||
|
||||
|
|
|
@ -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.
|
||||
|
|
|
@ -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
|
||||
----------------
|
||||
|
|
|
@ -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",
|
||||
|
|
55
pw_docgen/py/pw_docgen/sphinx/bug.py
Normal file
55
pw_docgen/py/pw_docgen/sphinx/bug.py
Normal file
|
@ -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,
|
||||
}
|
|
@ -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:
|
||||
|
||||
|
|
Loading…
Reference in New Issue
Block a user