diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt index 5cfce578a4a9e..ef6197dab7752 100644 --- a/doc/CMakeLists.txt +++ b/doc/CMakeLists.txt @@ -115,9 +115,19 @@ foreach(root ${DTS_ROOTS}) endforeach() if(DT_TURBO_MODE) + message(WARNING "DT 'turbo mode' is enabled.\n" + "The index of Devicetree bindings won't be generated and Sphinx roles such as " + ":dtcompatible: won't be able to link to them.") list(APPEND DTS_ARGS --turbo-mode) endif() +if(DOXYGENGROUPS_TURBO_MODE) + message(WARNING "Doxygen groups 'turbo mode' is enabled.\n" + "Doxygen groups won't be rendered in the documentation and Sphinx roles such as " + ":c:func: won't be able to link to them.") + list(APPEND SPHINXOPTS_EXTRA -D zephyr_breathe_skip_doxygen_groups=1) +endif() + add_custom_target( devicetree COMMAND ${CMAKE_COMMAND} -E env diff --git a/doc/Makefile b/doc/Makefile index 321a1b92cc403..85d55a0463fb6 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -8,6 +8,7 @@ SPHINXOPTS ?= -j auto -W --keep-going -T SPHINXOPTS_EXTRA ?= LATEXMKOPTS ?= -halt-on-error -no-shell-escape DT_TURBO_MODE ?= 0 +DOXYGENGROUPS_TURBO_MODE ?= 0 # ------------------------------------------------------------------------------ # Documentation targets @@ -15,7 +16,7 @@ DT_TURBO_MODE ?= 0 .PHONY: configure clean html html-fast latex pdf doxygen html-fast: - ${MAKE} html DT_TURBO_MODE=1 + ${MAKE} html DT_TURBO_MODE=1 DOXYGENGROUPS_TURBO_MODE=1 html latex pdf linkcheck doxygen: configure cmake --build ${BUILDDIR} --target $@ @@ -29,7 +30,8 @@ configure: -DSPHINXOPTS="${SPHINXOPTS}" \ -DSPHINXOPTS_EXTRA="${SPHINXOPTS_EXTRA}" \ -DLATEXMKOPTS="${LATEXMKOPTS}" \ - -DDT_TURBO_MODE=${DT_TURBO_MODE} + -DDT_TURBO_MODE=${DT_TURBO_MODE} \ + -DDOXYGENGROUPS_TURBO_MODE=${DOXYGENGROUPS_TURBO_MODE} clean: cmake --build ${BUILDDIR} --target clean diff --git a/doc/_extensions/zephyr/domain.py b/doc/_extensions/zephyr/domain.py index 66327f9c7adcd..d40aafb4f276d 100644 --- a/doc/_extensions/zephyr/domain.py +++ b/doc/_extensions/zephyr/domain.py @@ -307,16 +307,25 @@ class CustomDoxygenGroupDirective(DoxygenGroupDirective): """Monkey patch for Breathe's DoxygenGroupDirective.""" def run(self) -> List[Node]: - nodes = super().run() + if self.config.zephyr_breathe_skip_doxygen_groups: + note = nodes.attention() + note += nodes.Text( + f"Doxygen group {self.arguments[0]} was excluded from the documentation." + ) + + doxygengroup_node = [note] + else: + doxygengroup_node = super().run() if self.config.zephyr_breathe_insert_related_samples: - return [RelatedCodeSamplesNode(id=self.arguments[0]), *nodes] + return [RelatedCodeSamplesNode(id=self.arguments[0]), *doxygengroup_node] else: - return nodes + return doxygengroup_node def setup(app): app.add_config_value("zephyr_breathe_insert_related_samples", False, "env") + app.add_config_value("zephyr_breathe_skip_doxygen_groups", False, "env") app.add_domain(ZephyrDomain) diff --git a/doc/contribute/documentation/generation.rst b/doc/contribute/documentation/generation.rst index 87a00357c8938..de63378690936 100644 --- a/doc/contribute/documentation/generation.rst +++ b/doc/contribute/documentation/generation.rst @@ -264,18 +264,17 @@ Developer-mode Document Building ******************************** When making and testing major changes to the documentation, we provide an option -to temporarily stub-out the auto-generated Devicetree bindings documentation so -the doc build process runs faster. +to temporarily stub-out some of the more time-consuming parts of the build, such +as cross references to Doxygen-generated content, or Devicetree bindings +documentation, so that the doc build process runs faster. -To enable this mode, set the following option when invoking cmake:: +To enable this mode, set the following options when invoking cmake:: - -DDT_TURBO_MODE=1 + -DDT_TURBO_MODE=1 -DDOXYGENGROUPS_TURBO_MODE=1 or invoke make with the following target:: cd ~/zephyr - - # To generate HTML output without detailed Kconfig make html-fast Viewing generated documentation locally