diff --git a/Documentation/.gitignore b/Documentation/.gitignore index dda3b68e19..651dd9525f 100644 --- a/Documentation/.gitignore +++ b/Documentation/.gitignore @@ -1,2 +1,3 @@ /_build /.python-version +/_tags diff --git a/Documentation/Makefile b/Documentation/Makefile index b82d6729e1..16bbf15313 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -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 = . diff --git a/Documentation/Pipfile b/Documentation/Pipfile index 38e9071e62..edb3c5e260 100644 --- a/Documentation/Pipfile +++ b/Documentation/Pipfile @@ -15,3 +15,5 @@ sphinx-autobuild = "*" sphinx-copybutton = "*" pytz = "*" importlib-metadata = "*" +sphinx-tags = "*" +sphinx-design = "*" diff --git a/Documentation/conf.py b/Documentation/conf.py index afae714243..b025345b4a 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -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", +} diff --git a/Documentation/contributing/documentation.rst b/Documentation/contributing/documentation.rst index de5f02268d..5193eaf9a3 100644 --- a/Documentation/contributing/documentation.rst +++ b/Documentation/contributing/documentation.rst @@ -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 `_ 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 ---------------- diff --git a/Documentation/index.rst b/Documentation/index.rst index 6ebf6e01eb..ed213834d4 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -40,5 +40,6 @@ Last Updated: |today| guides/index.rst glossary.rst logos/index.rst + _tags/tagsindex.rst .. include:: substitutions.rst diff --git a/Documentation/platforms/arm/rp2040/boards/adafruit-feather-rp2040/index.rst b/Documentation/platforms/arm/rp2040/boards/adafruit-feather-rp2040/index.rst index c5febadec2..6440502af8 100644 --- a/Documentation/platforms/arm/rp2040/boards/adafruit-feather-rp2040/index.rst +++ b/Documentation/platforms/arm/rp2040/boards/adafruit-feather-rp2040/index.rst @@ -2,6 +2,8 @@ Adafruit Feather RP2040 ======================= +.. tags:: chip:rp2040 + The Feather RP2040 is a general purpose RP2040 board supplied by Adafruit. diff --git a/Documentation/platforms/arm/rp2040/boards/adafruit-kb2040/index.rst b/Documentation/platforms/arm/rp2040/boards/adafruit-kb2040/index.rst index d8a7481281..13c3c411b8 100644 --- a/Documentation/platforms/arm/rp2040/boards/adafruit-kb2040/index.rst +++ b/Documentation/platforms/arm/rp2040/boards/adafruit-kb2040/index.rst @@ -2,6 +2,8 @@ Adafruit KB2040 Kee Boar ======================== +.. tags:: chip:rp2040 + The KB2040 Kee Boar is a general purpose RP2040 board supplied by Adafruit. diff --git a/Documentation/platforms/arm/rp2040/boards/adafruit-qt-py-rp2040/index.rst b/Documentation/platforms/arm/rp2040/boards/adafruit-qt-py-rp2040/index.rst index cf4d62ec5a..abed91b31a 100644 --- a/Documentation/platforms/arm/rp2040/boards/adafruit-qt-py-rp2040/index.rst +++ b/Documentation/platforms/arm/rp2040/boards/adafruit-qt-py-rp2040/index.rst @@ -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. diff --git a/Documentation/platforms/arm/rp2040/boards/pimoroni-tiny2040/index.rst b/Documentation/platforms/arm/rp2040/boards/pimoroni-tiny2040/index.rst index 7616258034..997de387ea 100644 --- a/Documentation/platforms/arm/rp2040/boards/pimoroni-tiny2040/index.rst +++ b/Documentation/platforms/arm/rp2040/boards/pimoroni-tiny2040/index.rst @@ -2,6 +2,8 @@ Pimoroni Tiny2040 ================= +.. tags:: chip:rp2040 + The Tiny2040 is a general purpose RP2040 board supplied by Pimoroni. .. figure:: Tiny2040.png diff --git a/Documentation/platforms/arm/rp2040/boards/raspberrypi-pico-w/index.rst b/Documentation/platforms/arm/rp2040/boards/raspberrypi-pico-w/index.rst index db526ebf3a..34feb6e8d8 100644 --- a/Documentation/platforms/arm/rp2040/boards/raspberrypi-pico-w/index.rst +++ b/Documentation/platforms/arm/rp2040/boards/raspberrypi-pico-w/index.rst @@ -2,6 +2,8 @@ Raspberry Pi Pico W =============================== +.. tags:: chip:rp2040, wifi + The `Raspberry Pi Pico `_ is a general purpose board supplied by the Raspberry Pi Foundation. The W variant adds built in WiFi communications. diff --git a/Documentation/platforms/arm/rp2040/boards/raspberrypi-pico/index.rst b/Documentation/platforms/arm/rp2040/boards/raspberrypi-pico/index.rst index c8413fe9d3..bb7d36b627 100644 --- a/Documentation/platforms/arm/rp2040/boards/raspberrypi-pico/index.rst +++ b/Documentation/platforms/arm/rp2040/boards/raspberrypi-pico/index.rst @@ -2,6 +2,8 @@ Raspberry Pi Pico =============================== +.. tags:: chip:rp2040 + The `Raspberry Pi Pico `_ is a general purpose board supplied by the Raspberry Pi Foundation. diff --git a/Documentation/platforms/arm/rp2040/boards/seeed-xiao-rp2040/index.rst b/Documentation/platforms/arm/rp2040/boards/seeed-xiao-rp2040/index.rst index b4aa200b6b..51f4e8b3a1 100644 --- a/Documentation/platforms/arm/rp2040/boards/seeed-xiao-rp2040/index.rst +++ b/Documentation/platforms/arm/rp2040/boards/seeed-xiao-rp2040/index.rst @@ -2,6 +2,8 @@ Seeed Studio XIAO RP2040 ======================== +.. tags:: chip:rp2040 + The `Seeed Studio 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. diff --git a/Documentation/platforms/arm/rp2040/boards/w5500-evb-pico/index.rst b/Documentation/platforms/arm/rp2040/boards/w5500-evb-pico/index.rst index ba6dc9c0fb..3c251e8205 100644 --- a/Documentation/platforms/arm/rp2040/boards/w5500-evb-pico/index.rst +++ b/Documentation/platforms/arm/rp2040/boards/w5500-evb-pico/index.rst @@ -2,6 +2,8 @@ W5500-EVB-Pico =============================== +.. tags:: chip:rp2040, ethernet + The `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 diff --git a/Documentation/platforms/arm/rp2040/boards/waveshare-rp2040-lcd-1.28/index.rst b/Documentation/platforms/arm/rp2040/boards/waveshare-rp2040-lcd-1.28/index.rst index ed6a8a98e9..0b0c29b632 100644 --- a/Documentation/platforms/arm/rp2040/boards/waveshare-rp2040-lcd-1.28/index.rst +++ b/Documentation/platforms/arm/rp2040/boards/waveshare-rp2040-lcd-1.28/index.rst @@ -2,6 +2,8 @@ Waveshare RP2040 LCD 1.28 =============================== +.. tags:: chip:rp2040 + The `Waveshare RP2040 LCD 1.28 `_ is a low-cost, high-performance MCU board designed by Waveshare based on RP2040 with onboard 1.28 inch LCD. diff --git a/Documentation/platforms/arm/rp2040/boards/waveshare-rp2040-zero/index.rst b/Documentation/platforms/arm/rp2040/boards/waveshare-rp2040-zero/index.rst index 77969ae29b..a7c924cae6 100644 --- a/Documentation/platforms/arm/rp2040/boards/waveshare-rp2040-zero/index.rst +++ b/Documentation/platforms/arm/rp2040/boards/waveshare-rp2040-zero/index.rst @@ -2,6 +2,8 @@ Waveshare RP2040 Zero =============================== +.. tags:: chip:rp2040 + The `Waveshare RP2040 Zero `_ is a general purpose board supplied by Waveshare. diff --git a/Documentation/platforms/arm/rp2040/index.rst b/Documentation/platforms/arm/rp2040/index.rst index 09136a9679..ef86cfd106 100644 --- a/Documentation/platforms/arm/rp2040/index.rst +++ b/Documentation/platforms/arm/rp2040/index.rst @@ -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+. diff --git a/Documentation/platforms/arm64/bcm2711/boards/raspberrypi-4b/index.rst b/Documentation/platforms/arm64/bcm2711/boards/raspberrypi-4b/index.rst index cf2ad9ace0..c8028475a8 100644 --- a/Documentation/platforms/arm64/bcm2711/boards/raspberrypi-4b/index.rst +++ b/Documentation/platforms/arm64/bcm2711/boards/raspberrypi-4b/index.rst @@ -2,6 +2,8 @@ Raspberry Pi 4B =============== +.. tags:: experimental + The `Raspberry Pi 4B `_ is an ARM64 hobbyist board created by Raspberry Pi.