From b7aaa4c3aa750fb696e2ee686ef3850556d65348 Mon Sep 17 00:00:00 2001 From: Aksel Skauge Mellbye Date: Wed, 30 Apr 2025 18:11:08 +0200 Subject: [PATCH] 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 --- doc/CMakeLists.txt | 6 ++++++ doc/Makefile | 4 +++- doc/_extensions/zephyr/domain/__init__.py | 4 +++- doc/_scripts/gen_boards_catalog.py | 16 ++++++++++++---- doc/conf.py | 1 + doc/contribute/documentation/generation.rst | 13 +++++++++++++ doc/contribute/documentation/guidelines.rst | 5 +++++ 7 files changed, 43 insertions(+), 6 deletions(-) diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt index cb54555824df..d43b0c7c9670 100644 --- a/doc/CMakeLists.txt +++ b/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 STRING "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} diff --git a/doc/Makefile b/doc/Makefile index 4ce22f280f43..12b3ca371b02 100644 --- a/doc/Makefile +++ b/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 diff --git a/doc/_extensions/zephyr/domain/__init__.py b/doc/_extensions/zephyr/domain/__init__.py index 462b56527639..be2b38e0e647 100644 --- a/doc/_extensions/zephyr/domain/__init__.py +++ b/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) diff --git a/doc/_scripts/gen_boards_catalog.py b/doc/_scripts/gen_boards_catalog.py index 3771973a485b..41ccd7f97568 100755 --- a/doc/_scripts/gen_boards_catalog.py +++ b/doc/_scripts/gen_boards_catalog.py @@ -185,17 +185,17 @@ 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, f"{ZEPHYR_BASE}/scripts/twister", "-T", "samples/hello_world/", - "--all", "-M", *[arg for path in EDT_PICKLE_PATHS for arg in ('--keep-artifacts', path)], *[arg for path in RUNNERS_YAML_PATHS for arg in ('--keep-artifacts', path)], @@ -203,6 +203,12 @@ def run_twister_cmake_only(outdir): "--outdir", str(outdir), ] + if vendor_filter: + for vendor in vendor_filter: + twister_cmd += ["--vendor", vendor] + else: + twister_cmd += ["--all"] + minimal_env = { 'PATH': os.environ.get('PATH', ''), 'ZEPHYR_BASE': str(ZEPHYR_BASE), @@ -216,11 +222,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=None): """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 +264,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.") diff --git a/doc/conf.py b/doc/conf.py index fdafbdafd9ad..16a7c9e958d7 100644 --- a/doc/conf.py +++ b/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 -------------------------------------- diff --git a/doc/contribute/documentation/generation.rst b/doc/contribute/documentation/generation.rst index cad9201b113c..33f34dc4095b 100644 --- a/doc/contribute/documentation/generation.rst +++ b/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 *************************************** diff --git a/doc/contribute/documentation/guidelines.rst b/doc/contribute/documentation/guidelines.rst index 6c6b37a12f94..6b90a081662f 100644 --- a/doc/contribute/documentation/guidelines.rst +++ b/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