mirror of
https://github.com/apache/nuttx.git
synced 2025-05-08 22:32:04 +08:00
docs/tags: Introduce tagging feature to the documentation.
Introduces `sphinx-tags` to the documentation system, allowing individual pages to be tagged for better searching. The examples in this commit introduce the `chip:*` tag for indicating the chip a board uses, as well as the `experimental` tag for indicating experimental boards and features. Other tags indicate supported peripherals for boards, such as `wifi` and `ethernet`. Signed-off-by: Matteo Golin <matteo.golin@gmail.com>
This commit is contained in:
Matteo Golin
Mateusz Szafoni
parent
8c59326879
commit
4f652e0622
1
Documentation/.gitignore
vendored
1
Documentation/.gitignore
vendored
@ -1,2 +1,3 @@
|
||||
/_build
|
||||
/.python-version
|
||||
/_tags
|
||||
|
||||
@ -23,8 +23,9 @@
|
||||
|
||||
# You can set these variables from the command line, and also
|
||||
# from the environment for the first two.
|
||||
# Ignore the _tags directory as per sphinx-tags docs to avoid infinite loop
|
||||
SPHINXOPTS ?= -j 1 -W -A nuttx_versions="latest,${NUTTX_VERSIONS}"
|
||||
SPHINXAUTOOPTS ?= -j 8 -W
|
||||
SPHINXAUTOOPTS ?= -j 8 -W --ignore "_tags/*"
|
||||
SPHINXBUILD ?= sphinx-build
|
||||
SPHINXAUTOBUILD ?= sphinx-autobuild
|
||||
SOURCEDIR = .
|
||||
|
||||
@ -15,3 +15,5 @@ sphinx-autobuild = "*"
|
||||
sphinx-copybutton = "*"
|
||||
pytz = "*"
|
||||
importlib-metadata = "*"
|
||||
sphinx-tags = "*"
|
||||
sphinx-design = "*"
|
||||
|
||||
@ -59,6 +59,8 @@ extensions = [
|
||||
"sphinx_tabs.tabs",
|
||||
"sphinx_copybutton",
|
||||
"warnings_filter",
|
||||
"sphinx_tags",
|
||||
"sphinx_design",
|
||||
]
|
||||
|
||||
source_suffix = [".rst", ".md"]
|
||||
@ -77,7 +79,7 @@ templates_path = ["_templates"]
|
||||
# List of patterns, relative to source directory, that match files and
|
||||
# directories to ignore when looking for source files.
|
||||
# This pattern also affects html_static_path and html_extra_path.
|
||||
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "legacy_README.md"]
|
||||
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "legacy_README.md", "venv"]
|
||||
|
||||
# list of documentation versions to offer (besides latest). this will be
|
||||
# overridden by command line option but we can provide a sane default
|
||||
@ -132,3 +134,16 @@ copybutton_exclude = ".linenos, .gp, .go"
|
||||
# -- Options for warnings_filter ------------------------------------------
|
||||
|
||||
warnings_filter_config = "known-warnings.txt"
|
||||
|
||||
# -- Options for sphinx_tags ----------------------------------------------
|
||||
|
||||
tags_create_tags = True
|
||||
tags_page_title = "Tags"
|
||||
tags_page_header = "Pages with this tag"
|
||||
tags_overview_title = "Tags"
|
||||
|
||||
tags_create_badges = True
|
||||
tags_badge_colors = {
|
||||
"chip:*": "secondary",
|
||||
"experimental": "warning",
|
||||
}
|
||||
|
||||
@ -156,6 +156,19 @@ In case you need to leave a TODO note in the documentation to point that somethi
|
||||
which is available via the ``sphinx.ext.todo`` extension. This will let the reader of the documentation also know that the documentation
|
||||
is not yet finished somewhere and may further motivate a contribution.
|
||||
|
||||
Tags
|
||||
----
|
||||
|
||||
Use the ``tag`` admonition from `sphinx-tags <https://sphinx-tags.readthedocs.io/en/latest/quickstart.html#usage>`_ to
|
||||
tag your pages appropriately. This makes it easier for users to search and index the documentation. There are some tags
|
||||
which should always be included:
|
||||
|
||||
- ``chip:*`` tags are for board/chip documentation, to indicate which boards use which chip
|
||||
- ``experimental`` tags for boards/features that are experimental and should not be considered stable
|
||||
- Tags with the names of supported peripherals can be included for boards too, like ``wifi`` and ``ethernet``
|
||||
|
||||
Include the tags directive at the top of the page, with comma separators for each tag listed.
|
||||
|
||||
User Indications
|
||||
----------------
|
||||
|
||||
|
||||
@ -40,5 +40,6 @@ Last Updated: |today|
|
||||
guides/index.rst
|
||||
glossary.rst
|
||||
logos/index.rst
|
||||
_tags/tagsindex.rst
|
||||
|
||||
.. include:: substitutions.rst
|
||||
|
||||
@ -2,6 +2,8 @@
|
||||
Adafruit Feather RP2040
|
||||
=======================
|
||||
|
||||
.. tags:: chip:rp2040
|
||||
|
||||
The Feather RP2040 is a general purpose RP2040 board supplied by
|
||||
Adafruit.
|
||||
|
||||
|
||||
@ -2,6 +2,8 @@
|
||||
Adafruit KB2040 Kee Boar
|
||||
========================
|
||||
|
||||
.. tags:: chip:rp2040
|
||||
|
||||
The KB2040 Kee Boar is a general purpose RP2040 board supplied by
|
||||
Adafruit.
|
||||
|
||||
|
||||
@ -2,6 +2,8 @@
|
||||
Adafruit QT Py RP2040
|
||||
=======================
|
||||
|
||||
.. tags:: chip:rp2040
|
||||
|
||||
The QT Py RP2040 is a tiny general purpose RP2040 board supplied by
|
||||
Adafruit.
|
||||
|
||||
|
||||
@ -2,6 +2,8 @@
|
||||
Pimoroni Tiny2040
|
||||
=================
|
||||
|
||||
.. tags:: chip:rp2040
|
||||
|
||||
The Tiny2040 is a general purpose RP2040 board supplied by Pimoroni.
|
||||
|
||||
.. figure:: Tiny2040.png
|
||||
|
||||
@ -2,6 +2,8 @@
|
||||
Raspberry Pi Pico W
|
||||
===============================
|
||||
|
||||
.. tags:: chip:rp2040, wifi
|
||||
|
||||
The `Raspberry Pi Pico <https://www.raspberrypi.com/products/raspberry-pi-pico/>`_ is a general purpose board supplied by
|
||||
the Raspberry Pi Foundation. The W variant adds built in WiFi communications.
|
||||
|
||||
|
||||
@ -2,6 +2,8 @@
|
||||
Raspberry Pi Pico
|
||||
===============================
|
||||
|
||||
.. tags:: chip:rp2040
|
||||
|
||||
The `Raspberry Pi Pico <https://www.raspberrypi.com/products/raspberry-pi-pico/>`_ is a general purpose board supplied by
|
||||
the Raspberry Pi Foundation.
|
||||
|
||||
|
||||
@ -2,6 +2,8 @@
|
||||
Seeed Studio XIAO RP2040
|
||||
========================
|
||||
|
||||
.. tags:: chip:rp2040
|
||||
|
||||
The `Seeed Studio Xiao RP2040 <https://wiki.seeedstudio.com/XIAO-RP2040/>`_ is a general purpose board supplied by
|
||||
Seeed Studio and it is compatible with the Raspberry Pi RP2040 ecosystem as they share the same RP2040 chip.
|
||||
|
||||
|
||||
@ -2,6 +2,8 @@
|
||||
W5500-EVB-Pico
|
||||
===============================
|
||||
|
||||
.. tags:: chip:rp2040, ethernet
|
||||
|
||||
The `W5500-EVB-Pico <https://docs.wiznet.io/Product/iEthernet/W5500/w5500-evb-pico/>`_
|
||||
is a microcontroller evaluation board based on the Raspberry Pi RP2040 and fully
|
||||
hardwired TCP/IP controller W5500 – and basically works the same as Raspberry Pi
|
||||
|
||||
@ -2,6 +2,8 @@
|
||||
Waveshare RP2040 LCD 1.28
|
||||
===============================
|
||||
|
||||
.. tags:: chip:rp2040
|
||||
|
||||
The `Waveshare RP2040 LCD 1.28 <https://www.waveshare.com/wiki/RP2040-LCD-1.28>`_
|
||||
is a low-cost, high-performance MCU board designed by Waveshare based on RP2040
|
||||
with onboard 1.28 inch LCD.
|
||||
|
||||
@ -2,6 +2,8 @@
|
||||
Waveshare RP2040 Zero
|
||||
===============================
|
||||
|
||||
.. tags:: chip:rp2040
|
||||
|
||||
The `Waveshare RP2040 Zero <https://www.waveshare.com/wiki/RP2040-Zero>`_ is a general purpose board supplied by
|
||||
Waveshare.
|
||||
|
||||
|
||||
@ -2,6 +2,8 @@
|
||||
RaspberryPi rp2040
|
||||
==================
|
||||
|
||||
.. tags:: chip:rp2040
|
||||
|
||||
The rp2040 is a dual core chip produced by the RaspberryPi Foundation that
|
||||
is based on ARM Cortex-M0+.
|
||||
|
||||
|
||||
@ -2,6 +2,8 @@
|
||||
Raspberry Pi 4B
|
||||
===============
|
||||
|
||||
.. tags:: experimental
|
||||
|
||||
The `Raspberry Pi 4B <https://www.raspberrypi.com/products/raspberry-pi-4-model-b/specifications/>`_ is an ARM64
|
||||
hobbyist board created by Raspberry Pi.
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user