doc: extensions: boards: add ability to filter by hw capability

.github/workflows/doc-build.yml

@@ -10,6 +10,7 @@ on:
     tags:
     - v*
   pull_request:
+  workflow_dispatch:
 
 env:
   # NOTE: west docstrings will be extracted from the version listed here
@@ -26,8 +27,8 @@ jobs:
   doc-file-check:
     name: Check for doc changes
     runs-on: ubuntu-22.04
-    if: >
-      github.repository_owner == 'zephyrproject-rtos'
+    # if: >
+    #   github.repository_owner = 'zephyrproject-rtos'
     outputs:
       file_check: ${{ steps.check-doc-files.outputs.any_modified }}
     steps:
@@ -61,15 +62,22 @@ jobs:
     name: "Documentation Build (HTML)"
     needs: [doc-file-check]
     if: >
-      github.repository_owner == 'zephyrproject-rtos' &&
         ( needs.doc-file-check.outputs.file_check == 'true' || github.event_name != 'pull_request' )
+    # runs-on: ${{ (github.event_name != 'pull_request') && fromJSON('{"group":"zephyr-runner-v2-linux-x64-4xlarge"}') || 'ubuntu-22.04' }}
     runs-on: ubuntu-22.04
     timeout-minutes: 90
     concurrency:
       group: doc-build-html-${{ github.ref }}
       cancel-in-progress: true
 
     steps:
+    - name: Print cloud service information
+      if: needs.doc-file-check.outputs.file_check == 'true' && github.event_name == 'pull_request'
+      run: |
+        echo "ZEPHYR_RUNNER_CLOUD_PROVIDER = ${ZEPHYR_RUNNER_CLOUD_PROVIDER}"
+        echo "ZEPHYR_RUNNER_CLOUD_NODE = ${ZEPHYR_RUNNER_CLOUD_NODE}"
+        echo "ZEPHYR_RUNNER_CLOUD_POD = ${ZEPHYR_RUNNER_CLOUD_POD}"
+
     - name: install-pkgs
       run: |
         sudo apt-get update
@@ -84,13 +92,15 @@ jobs:
       with:
         ref: ${{ github.event.pull_request.head.sha }}
         fetch-depth: 0
+        path: zephyr
 
     - name: Rebase
       if: github.event_name == 'pull_request'
       continue-on-error: true
       env:
         BASE_REF: ${{ github.base_ref }}
         PR_HEAD: ${{ github.event.pull_request.head.sha }}
+      working-directory: zephyr
       run: |
         git config --global user.email "actions@zephyrproject.org"
         git config --global user.name "Github Actions"
@@ -100,25 +110,27 @@ jobs:
         git clean -f -d
         git log --graph --oneline HEAD...${PR_HEAD}
 
-    - name: cache-pip
-      uses: actions/cache@v4
+    - name: Setup Zephyr project
+      uses: zephyrproject-rtos/action-zephyr-setup@v1
       with:
-        path: ~/.cache/pip
-        key: pip-${{ hashFiles('doc/requirements.txt') }}
+        app-path: zephyr
+        toolchains: ${{ github.event_name != 'pull_request' && 'all' || null }}
 
     - name: install-pip
+      working-directory: zephyr
       run: |
         pip install -r doc/requirements.txt
-        pip install west==${WEST_VERSION}
-        pip install cmake==${CMAKE_VERSION}
         pip install coverxygen
 
-    - name: west setup
+    - name: Build hello_world on all boards
+      if: github.event_name != 'pull_request'
+      working-directory: zephyr
       run: |
-        west init -l .
+        ./scripts/twister -vvv -T samples/hello_world/ --all --cmake-only -M
 
     - name: build-docs
       shell: bash
+      working-directory: zephyr
       run: |
         if [[ "$GITHUB_REF" =~ "refs/tags/v" ]]; then
           DOC_TAG="release"
@@ -144,16 +156,17 @@ jobs:
         genhtml --no-function-coverage --no-branch-coverage new.info -o coverage-report
 
     - name: compress-docs
+      working-directory: zephyr
       run: |
-        tar --use-compress-program="xz -T0" -cf html-output.tar.xz --directory=doc/_build html
+        tar --use-compress-program="xz -T0" -cf html-output.tar.xz --exclude doc/_build/_sources --exclude doc/_build/doxygen/xml --directory=doc/_build html
         tar --use-compress-program="xz -T0" -cf api-output.tar.xz --directory=doc/_build html/doxygen/html
         tar --use-compress-program="xz -T0" -cf api-coverage.tar.xz coverage-report
 
     - name: upload-build
       uses: actions/upload-artifact@v4
       with:
         name: html-output
-        path: html-output.tar.xz
+        path: zephyr/html-output.tar.xz
 
     - name: upload-api-coverage
       uses: actions/upload-artifact@v4

boards/raspberrypi/rpi_pico2/doc/index.rst

@@ -79,7 +79,8 @@ hardware features:
 Connections and IOs
 ===================
 
-The default pin mapping is unchanged from the Pico 1 (see :ref:`rpi_pico_pin_mapping`).
+The default pin mapping is unchanged from the Pico 1 (see
+:ref:`Raspberry Pi Pico Pin Mapping <rpi_pico_pin_mapping>`).
 
 Programming and Debugging
 *************************

doc/CMakeLists.txt

@@ -16,6 +16,7 @@ set(SPHINXOPTS "-j auto -W --keep-going -T" CACHE STRING "Default Sphinx Options
 set(SPHINXOPTS_EXTRA "" CACHE STRING "Extra Sphinx Options (added to defaults)")
 set(LATEXMKOPTS "-halt-on-error -no-shell-escape" CACHE STRING "Default latexmk options")
 set(DT_TURBO_MODE OFF CACHE BOOL "Enable DT turbo mode")
+set(HW_FEATURES_TURBO_MODE OFF CACHE BOOL "Enable HW features turbo mode")
 set(DOC_TAG "development" CACHE STRING "Documentation tag")
 set(DTS_ROOTS "${ZEPHYR_BASE}" CACHE STRING "DT bindings root folders")
 
@@ -149,6 +150,16 @@ set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS ${GEN_DEVICETREE_
 #-------------------------------------------------------------------------------
 # html
 
+set(SPHINX_TAGS "${DOC_TAG}")
+if(HW_FEATURES_TURBO_MODE)
+  list(APPEND SPHINX_TAGS "hw_features_turbo")
+endif()
+
+set(SPHINX_TAGS_ARGS "")
+foreach(tag ${SPHINX_TAGS})
+  list(APPEND SPHINX_TAGS_ARGS "-t" "${tag}")
+endforeach()
+
 add_doc_target(
   html
   COMMAND ${CMAKE_COMMAND} -E env ${SPHINX_ENV} OUTPUT_DIR=${DOCS_HTML_DIR}
@@ -157,7 +168,7 @@ add_doc_target(
     -c ${DOCS_CFG_DIR}
     -d ${DOCS_DOCTREE_DIR}
     -w ${DOCS_BUILD_DIR}/html.log
-    -t ${DOC_TAG}
+    ${SPHINX_TAGS_ARGS}
     ${SPHINXOPTS}
     ${SPHINXOPTS_EXTRA}
     ${DOCS_SRC_DIR}
@@ -187,7 +198,7 @@ add_doc_target(
     -c ${DOCS_CFG_DIR}
     -d ${DOCS_DOCTREE_DIR}
     -w ${DOCS_BUILD_DIR}/html.log
-    -t ${DOC_TAG}
+    ${SPHINX_TAGS_ARGS}
     ${SPHINXOPTS}
     ${SPHINXOPTS_EXTRA}
     ${DOCS_SRC_DIR}
@@ -203,6 +214,7 @@ set_target_properties(
 )
 
 add_dependencies(html-live devicetree)
+
 #-------------------------------------------------------------------------------
 # pdf
 
@@ -214,7 +226,7 @@ add_doc_target(
     -c ${DOCS_CFG_DIR}
     -d ${DOCS_DOCTREE_DIR}
     -w ${DOCS_BUILD_DIR}/latex.log
-    -t ${DOC_TAG}
+    ${SPHINX_TAGS_ARGS}
     -t convertimages
     ${SPHINXOPTS}
     ${SPHINXOPTS_EXTRA}
@@ -266,7 +278,7 @@ add_doc_target(
     -c ${DOCS_CFG_DIR}
     -d ${DOCS_DOCTREE_DIR}
     -w ${DOCS_BUILD_DIR}/linkcheck.log
-    -t ${DOC_TAG}
+    ${SPHINX_TAGS_ARGS}
     ${SPHINXOPTS}
     ${SPHINXOPTS_EXTRA}
     ${DOCS_SRC_DIR}

doc/Makefile

@@ -8,17 +8,18 @@ SPHINXOPTS ?= -j auto -W --keep-going -T
 SPHINXOPTS_EXTRA ?=
 LATEXMKOPTS ?= -halt-on-error -no-shell-escape
 DT_TURBO_MODE ?= 0
+HW_FEATURES_TURBO_MODE ?= 0
 
 # ------------------------------------------------------------------------------
 # Documentation targets
 
 .PHONY: configure clean html html-fast html-live html-live-fast latex pdf doxygen
 
 html-fast:
-	${MAKE} html DT_TURBO_MODE=1
+	${MAKE} html DT_TURBO_MODE=1 HW_FEATURES_TURBO_MODE=1
 
 html-live-fast:
-	${MAKE} html-live DT_TURBO_MODE=1
+	${MAKE} html-live DT_TURBO_MODE=1 HW_FEATURES_TURBO_MODE=1
 
 html html-live latex pdf linkcheck doxygen: configure
 	cmake --build ${BUILDDIR} --target $@
@@ -32,7 +33,8 @@ configure:
 		-DSPHINXOPTS="${SPHINXOPTS}" \
 		-DSPHINXOPTS_EXTRA="${SPHINXOPTS_EXTRA}" \
 		-DLATEXMKOPTS="${LATEXMKOPTS}" \
-		-DDT_TURBO_MODE=${DT_TURBO_MODE}
+		-DDT_TURBO_MODE=${DT_TURBO_MODE} \
+		-DHW_FEATURES_TURBO_MODE=${HW_FEATURES_TURBO_MODE}
 
 clean:
 	cmake --build ${BUILDDIR} --target clean

doc/_extensions/zephyr/domain/__init__.py

@@ -53,6 +53,8 @@
 from zephyr.doxybridge import DoxygenGroupDirective
 from zephyr.gh_utils import gh_link_get_url
 
+from .binding_types import BINDING_TYPES
+
 __version__ = "0.2.0"
 
 
@@ -67,6 +69,16 @@
 
 logger = logging.getLogger(__name__)
 
+BINDING_TYPE_TO_DOCUTILS_NODE = {}
+for key, value in BINDING_TYPES.items():
+    if isinstance(value, tuple):
+        # For abbreviations with explanations
+        abbr, explanation = value
+        BINDING_TYPE_TO_DOCUTILS_NODE[key] = nodes.abbreviation(abbr, abbr, explanation=explanation)
+    else:
+        # For simple text
+        BINDING_TYPE_TO_DOCUTILS_NODE[key] = nodes.Text(value)
+
 
 class CodeSampleNode(nodes.Element):
     pass
@@ -224,6 +236,110 @@ def apply(self):
         for node in self.document.traverse(matcher):
             self.convert_node(node)
 
+    class FindSupportedFeaturesSectionVisitor(nodes.SparseNodeVisitor):
+        def __init__(self, document, supported_features):
+            super().__init__(document)
+            self.supported_features = supported_features
+
+        def visit_section(self, node):
+            if not (node.children and node.children[0].astext() == "Supported Features"):
+                return
+
+            table = self._create_table()
+            tbody = self._create_table_body()
+            table.children[0] += tbody
+
+            # Replace section contents with title and new table
+            title = node.children[0]
+            node.clear()
+            node += title
+            node += table
+
+        def _create_table(self):
+            """Create the table structure with headers"""
+            table = nodes.table(classes=["colwidths-given"])
+            tgroup = nodes.tgroup(cols=3)
+
+            tgroup += nodes.colspec(colwidth=20, classes=["col-1"])
+            tgroup += nodes.colspec(colwidth=50)
+            tgroup += nodes.colspec(colwidth=30)
+
+            thead = self._create_header_row()
+            tgroup += thead
+
+            table += tgroup
+            return table
+
+        def _create_header_row(self):
+            """Create the table header row"""
+            thead = nodes.thead()
+            row = nodes.row()
+            headers = ["Type", "Description", "Compatible"]
+            for header in headers:
+                row += nodes.entry("", nodes.paragraph(text=header))
+            thead += row
+            return thead
+
+        def _create_table_body(self):
+            """Create the table body with feature rows"""
+            tbody = nodes.tbody()
+
+            def feature_sort_key(feature):
+                if feature == "cpu":
+                    return (0, feature)
+                return (1, feature)
+
+            sorted_features = sorted(self.supported_features.keys(), key=feature_sort_key)
+
+            for feature in sorted_features:
+                items = list(self.supported_features[feature].items())
+                self._add_feature_rows(tbody, feature, items)
+
+            return tbody
+
+        def _add_feature_rows(self, tbody, feature, items):
+            """Add rows for a specific feature"""
+            num_items = len(items)
+
+            for i, (key, value) in enumerate(items):
+                row = nodes.row()
+
+                # Add type column only for first row of a feature
+                if i == 0:
+                    type_entry = self._create_type_entry(feature, num_items)
+                    row += type_entry
+
+                row += nodes.entry("", nodes.paragraph(text=value))
+                row += nodes.entry("", nodes.paragraph("", "", self._create_compatible_xref(key)))
+
+                tbody += row
+
+        def _create_type_entry(self, feature, rowspan):
+            """Create the type entry with proper text and rowspan"""
+            type_entry = nodes.entry(morerows=rowspan - 1)
+            type_entry += nodes.paragraph(
+                "",
+                "",
+                BINDING_TYPE_TO_DOCUTILS_NODE.get(feature, nodes.Text(feature)).deepcopy(),
+            )
+            return type_entry
+
+        def _create_compatible_xref(self, key):
+            """Create a cross-reference for the compatible field"""
+            xref = addnodes.pending_xref(
+                "",
+                refdomain="std",
+                reftype="dtcompatible",
+                reftarget=key,
+                refexplicit=False,
+                refwarn=True,
+            )
+            xref += nodes.literal(text=key)
+            return xref
+
+        def unknown_visit(self, node):
+            pass
+
     def convert_node(self, node):
         parent = node.parent
         siblings_to_move = []
@@ -289,6 +405,14 @@ def convert_node(self, node):
             # Replace the custom node with the new section
             node.replace_self(new_section)
 
+            # patch existing supported features section.
+            # in the future, this should (maybe) be an explicit
+            # .. zephyr:board-features:: directive instead.
+            visitsections = self.FindSupportedFeaturesSectionVisitor(
+                self.document, node["supported_features"]
+            )
+            self.document.walk(visitsections)
+
             # Remove the moved siblings from their original parent
             for sibling in siblings_to_move:
                 parent.remove(sibling)
@@ -685,6 +809,7 @@ def run(self):
             board_node = BoardNode(id=board_name)
             board_node["full_name"] = board["full_name"]
             board_node["vendor"] = vendors.get(board["vendor"], board["vendor"])
+            board_node["supported_features"] = board["supported_features"]
             board_node["archs"] = board["archs"]
             board_node["socs"] = board["socs"]
             board_node["image"] = board["image"]
@@ -962,6 +1087,7 @@ def load_board_catalog_into_domain(app: Sphinx) -> None:
 
 def setup(app):
     app.add_config_value("zephyr_breathe_insert_related_samples", False, "env")
+    app.add_config_value("zephyr_generate_hw_features", False, "env")
 
     app.add_domain(ZephyrDomain)