doc: Add vendor filter for hw feature generation

The hw feature generation takes a long time. The HW_FEATURES_TURBO_MODE
option completely disables hw feature generation. Add a new option
HW_FEATURES_VENDOR_FILTER to be able to selectively enable hw feature
generation only for a given list of vendors. This option is useful
when working on board documentation pages.

Signed-off-by: Aksel Skauge Mellbye <[email protected]>

Author: asmellby

doc/CMakeLists.txt

@@ -17,6 +17,7 @@ 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(HW_FEATURES_VENDOR_FILTER "" CACHE BOOL "Vendor filter for HW features")
 set(DOC_TAG "development" CACHE STRING "Documentation tag")
 set(DTS_ROOTS "${ZEPHYR_BASE}" CACHE STRING "DT bindings root folders")
 
@@ -160,6 +161,11 @@ foreach(tag ${SPHINX_TAGS})
   list(APPEND SPHINX_TAGS_ARGS "-t" "${tag}")
 endforeach()
 
+if(HW_FEATURES_VENDOR_FILTER)
+  list(JOIN HW_FEATURES_VENDOR_FILTER "," vendor_filter)
+  list(APPEND SPHINXOPTS "-D" "zephyr_hw_features_vendor_filter=${vendor_filter}")
+endif()
+
 add_doc_target(
   html
   COMMAND ${CMAKE_COMMAND} -E env ${SPHINX_ENV} OUTPUT_DIR=${DOCS_HTML_DIR}

doc/Makefile

@@ -9,6 +9,7 @@ SPHINXOPTS_EXTRA ?=
 LATEXMKOPTS ?= -halt-on-error -no-shell-escape
 DT_TURBO_MODE ?= 0
 HW_FEATURES_TURBO_MODE ?= 0
+HW_FEATURES_VENDOR_FILTER ?=
 
 # ------------------------------------------------------------------------------
 # Documentation targets
@@ -34,7 +35,8 @@ configure:
 		-DSPHINXOPTS_EXTRA="${SPHINXOPTS_EXTRA}" \
 		-DLATEXMKOPTS="${LATEXMKOPTS}" \
 		-DDT_TURBO_MODE=${DT_TURBO_MODE} \
-		-DHW_FEATURES_TURBO_MODE=${HW_FEATURES_TURBO_MODE}
+		-DHW_FEATURES_TURBO_MODE=${HW_FEATURES_TURBO_MODE} \
+		-DHW_FEATURES_VENDOR_FILTER=${HW_FEATURES_VENDOR_FILTER}
 
 clean:
 	cmake --build ${BUILDDIR} --target clean

doc/_extensions/zephyr/domain/__init__.py

@@ -1366,7 +1366,8 @@ def load_board_catalog_into_domain(app: Sphinx) -> None:
     board_catalog = get_catalog(
         generate_hw_features=(
             app.builder.format == "html" and app.config.zephyr_generate_hw_features
-        )
+        ),
+        hw_features_vendor_filter=app.config.zephyr_hw_features_vendor_filter
     )
     app.env.domaindata["zephyr"]["boards"] = board_catalog["boards"]
     app.env.domaindata["zephyr"]["vendors"] = board_catalog["vendors"]
@@ -1377,6 +1378,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_config_value("zephyr_hw_features_vendor_filter", [], "env", types=[list[str]])
 
     app.add_domain(ZephyrDomain)
 

doc/_scripts/gen_boards_catalog.py

@@ -185,11 +185,12 @@ def gather_board_build_info(twister_out_dir):
     return board_devicetrees, board_runners
 
 
-def run_twister_cmake_only(outdir):
+def run_twister_cmake_only(outdir, vendor_filter):
     """Run twister in cmake-only mode to generate build info files.
 
     Args:
         outdir: Directory where twister should output its files
+        vendor_filter: Limit build info to boards from listed vendors
     """
     twister_cmd = [
         sys.executable,
@@ -203,6 +204,9 @@ def run_twister_cmake_only(outdir):
         "--outdir", str(outdir),
     ]
 
+    for vendor in vendor_filter:
+        twister_cmd += ["--vendor", vendor]
+
     minimal_env = {
         'PATH': os.environ.get('PATH', ''),
         'ZEPHYR_BASE': str(ZEPHYR_BASE),
@@ -216,11 +220,13 @@ def run_twister_cmake_only(outdir):
         logger.warning(f"Failed to run Twister, list of hw features might be incomplete.\n{e}")
 
 
-def get_catalog(generate_hw_features=False):
+def get_catalog(generate_hw_features=False, hw_features_vendor_filter=[]):
     """Get the board catalog.
 
     Args:
         generate_hw_features: If True, run twister to generate hardware features information.
+        hw_features_vendor_filter: If generate_hw_features is True, limit hardware feature
+                                   information generation to boards from this list of vendors.
     """
     import tempfile
 
@@ -256,7 +262,7 @@ def get_catalog(generate_hw_features=False):
     if generate_hw_features:
         logger.info("Running twister in cmake-only mode to get Devicetree files for all boards")
         with tempfile.TemporaryDirectory() as tmp_dir:
-            run_twister_cmake_only(tmp_dir)
+            run_twister_cmake_only(tmp_dir, hw_features_vendor_filter)
             board_devicetrees, board_runners = gather_board_build_info(Path(tmp_dir))
     else:
         logger.info("Skipping generation of supported hardware features.")

doc/conf.py

@@ -327,6 +327,7 @@
 
 zephyr_breathe_insert_related_samples = True
 zephyr_generate_hw_features = not tags.has("hw_features_turbo")  # pylint: disable=undefined-variable  # noqa: F821
+zephyr_hw_features_vendor_filter = []
 
 # -- Options for sphinx.ext.graphviz --------------------------------------
 

doc/contribute/documentation/generation.rst

@@ -268,6 +268,19 @@ without either of the aforementioned features::
    # and supported features index
    make html-fast
 
+When working with documentation for boards from a specific vendor, it is also
+possible to limit generation of the list of supported features to subset of board
+vendors. This can be done by setting the following option when invoking cmake::
+
+   -DHW_FEATURES_VENDOR_FILTER=vendor1,vendor2
+
+This option can also be used with the :command:`make` wrapper::
+
+   cd ~/zephyrproject/zephyr/doc
+
+   # To generate HTML output with supported features limited to a subset of vendors
+   make html HW_FEATURES_VENDOR_FILTER=vendor1,vendor2
+
 Viewing generated documentation locally
 ***************************************
 

doc/contribute/documentation/guidelines.rst

@@ -1281,6 +1281,11 @@ Boards
       (``zephyr_generate_hw_features`` config option set to ``True``). If disabled, a warning message
       will be shown instead of the hardware features tables.
 
+      It is possible to limit the hardware features generation to boards from a specific list of vendors
+      to speed up documentation builds without completely disabling the hardware features table. Set the
+      config option ``zephyr_hw_features_vendor_filter`` to the list of vendors to generate features for.
+      If the option is empty, hardware features are generated for all boards from all vendors.
+
 .. rst:directive:: .. zephyr:board-supported-runners::
 
    This directive is used to show the supported runners for the board documented in the current