From 5986d882bb6fe1e67aca564656d09f87841fe4f9 Mon Sep 17 00:00:00 2001 From: Gerard Marull-Paretas Date: Wed, 2 Feb 2022 20:09:01 +0100 Subject: [PATCH] doc: add support for DT_TURBO_MODE Similar to Kconfig turbo mode, add a Devicetree bindings turbo mode. In this mode, the Devicetree bindings pages are not generated. Instead, a page with dummy symbols is created. This takes ~1K pages out of the build, resulting in faster builds. This mode can be useful while in development or CI PRs. Signed-off-by: Gerard Marull-Paretas --- doc/CMakeLists.txt | 11 ++++++--- doc/Makefile | 6 +++-- doc/_scripts/gen_devicetree_rest.py | 37 +++++++++++++++++++++++++---- 3 files changed, 45 insertions(+), 9 deletions(-) diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt index fd20f6dce5..2140a7338c 100644 --- a/doc/CMakeLists.txt +++ b/doc/CMakeLists.txt @@ -14,6 +14,7 @@ message(STATUS "Zephyr base: ${ZEPHYR_BASE}") set(SPHINXOPTS "-j auto" CACHE STRING "Default Sphinx Options") 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(DOC_TAG "development" CACHE STRING "Documentation tag") set(DTS_ROOTS "${ZEPHYR_BASE}" CACHE STRING "DT bindings root folders") @@ -170,11 +171,15 @@ set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS ${GEN_KCONFIG_RES set(GEN_DEVICETREE_REST_SCRIPT ${CMAKE_CURRENT_LIST_DIR}/_scripts/gen_devicetree_rest.py) -set(DTS_ROOT_ARGS) +set(DTS_ARGS) foreach(root ${DTS_ROOTS}) - list(APPEND DTS_ROOT_ARGS --dts-root ${root}) + list(APPEND DTS_ARGS --dts-root ${root}) endforeach() +if(DT_TURBO_MODE) + list(APPEND DTS_ARGS --turbo-mode) +endif() + add_custom_target( devicetree COMMAND ${CMAKE_COMMAND} -E env @@ -182,7 +187,7 @@ add_custom_target( ZEPHYR_BASE=${ZEPHYR_BASE} ${PYTHON_EXECUTABLE} ${GEN_DEVICETREE_REST_SCRIPT} --vendor-prefixes ${ZEPHYR_BASE}/dts/bindings/vendor-prefixes.txt - ${DTS_ROOT_ARGS} + ${DTS_ARGS} ${DOCS_SRC_DIR}/reference/devicetree VERBATIM USES_TERMINAL diff --git a/doc/Makefile b/doc/Makefile index 2d5f1a09b5..f311b634fc 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -7,6 +7,7 @@ DOC_TAG ?= development SPHINXOPTS ?= -j auto LATEXMKOPTS ?= -halt-on-error -no-shell-escape KCONFIG_TURBO_MODE ?= 0 +DT_TURBO_MODE ?= 0 # ------------------------------------------------------------------------------ # Documentation targets @@ -14,7 +15,7 @@ KCONFIG_TURBO_MODE ?= 0 .PHONY: configure clean html html-fast latex pdf doxygen html-fast: - ${MAKE} html KCONFIG_TURBO_MODE=1 + ${MAKE} html KCONFIG_TURBO_MODE=1 DT_TURBO_MODE=1 html latex pdf doxygen: configure cmake --build ${BUILDDIR} --target $@ @@ -27,7 +28,8 @@ configure: -DDOC_TAG=${DOC_TAG} \ -DSPHINXOPTS="${SPHINXOPTS}" \ -DLATEXMKOPTS="${LATEXMKOPTS}" \ - -DKCONFIG_TURBO_MODE=${KCONFIG_TURBO_MODE} + -DKCONFIG_TURBO_MODE=${KCONFIG_TURBO_MODE} \ + -DDT_TURBO_MODE=${DT_TURBO_MODE} clean: cmake --build ${BUILDDIR} --target clean diff --git a/doc/_scripts/gen_devicetree_rest.py b/doc/_scripts/gen_devicetree_rest.py index 746275f5d5..70d73535a0 100644 --- a/doc/_scripts/gen_devicetree_rest.py +++ b/doc/_scripts/gen_devicetree_rest.py @@ -166,7 +166,8 @@ def main(): bindings = load_bindings(args.dts_roots) base_binding = load_base_binding() vnd_lookup = VndLookup(args.vendor_prefixes, bindings) - dump_content(bindings, base_binding, vnd_lookup, args.out_dir) + dump_content(bindings, base_binding, vnd_lookup, args.out_dir, + args.turbo_mode) def parse_args(): # Parse command line arguments from sys.argv. @@ -179,6 +180,8 @@ def parse_args(): parser.add_argument('--dts-root', dest='dts_roots', action='append', help='''additional DTS root directory as it would be set in DTS_ROOTS''') + parser.add_argument('--turbo-mode', action='store_true', + help='Enable turbo mode (dummy references)') parser.add_argument('out_dir', help='output files are generated here') return parser.parse_args() @@ -233,7 +236,7 @@ def load_base_binding(): return edtlib.Binding(os.fspath(base_yaml), base_includes, require_compatible=False, require_description=False) -def dump_content(bindings, base_binding, vnd_lookup, out_dir): +def dump_content(bindings, base_binding, vnd_lookup, out_dir, turbo_mode): # Dump the generated .rst files for a vnd2bindings dict. # Files are only written if they are changed. Existing .rst # files which would not be written by the 'vnd2bindings' @@ -242,8 +245,11 @@ def dump_content(bindings, base_binding, vnd_lookup, out_dir): out_dir = Path(out_dir) setup_bindings_dir(bindings, out_dir) - write_bindings_rst(vnd_lookup, out_dir) - write_orphans(bindings, base_binding, vnd_lookup, out_dir) + if turbo_mode: + write_dummy_index(bindings, out_dir) + else: + write_bindings_rst(vnd_lookup, out_dir) + write_orphans(bindings, base_binding, vnd_lookup, out_dir) def setup_bindings_dir(bindings, out_dir): # Make a set of all the Path objects we will be creating for @@ -266,6 +272,29 @@ def setup_bindings_dir(bindings, out_dir): logger.info('removing unexpected file %s', path) path.unlink() + +def write_dummy_index(bindings, out_dir): + # Write out_dir / bindings.rst, with dummy anchors + + # header + content = '\n'.join(( + '.. _devicetree_binding_index:', + '.. _dt_vendor_zephyr:', + '', + 'Dummy bindings index', + '####################', + '', + )) + + # build compatibles set and dump it + compatibles = {binding.compatible for binding in bindings} + content += '\n'.join(( + f'.. dtcompatible:: {compatible}' for compatible in compatibles + )) + + write_if_updated(out_dir / 'bindings.rst', content) + + def write_bindings_rst(vnd_lookup, out_dir): # Write out_dir / bindings.rst, the top level index of bindings.