From 6cc238accc95ee3b4ab5efc2fe455d701d44057a Mon Sep 17 00:00:00 2001
From: Marc Herbert <marc.herbert@intel.com>
Date: Sat, 11 Mar 2023 07:21:30 +0000
Subject: [PATCH] doc: add `minimal` sphinx tag that turns off very slow
 features

The incremental doc build has become too slow again, unusable for
interactive use and "drive-by" doc fixes. Add a new `minimal` sphinx tag
that groups and optionally disables all features unusable for
interactive use.

On a 6 years old server with 72 cores and 300G of RAM, this new
`minimal` tag reduces `html-fast` build times like this:

- Build from scratch:

  From 4.5 minutes down to 1 minute

- Incremental build, one-character .rst change:

  From 16 seconds down to 9 seconds.

Signed-off-by: Marc Herbert <marc.herbert@intel.com>
(cherry picked from commit 2f675be6383b4925f4cf74ca86a3c0d8663482f8)
---
 doc/Makefile | 10 ++++++++++
 doc/conf.py  | 10 ++++++++--
 2 files changed, 18 insertions(+), 2 deletions(-)

diff --git a/doc/Makefile b/doc/Makefile
index c9ae0e700978a..c2cc51f0c3ce2 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -16,6 +16,16 @@ DT_TURBO_MODE ?= 0
 html-fast:
 	${MAKE} html DT_TURBO_MODE=1
 
+# The `minimal` tag turns off all slow sphinx features for a much faster
+# incremental build when editing .rst files interactively. As usual when
+# making significant sphinx configuration changes, you must delete
+# doc/_build/ first. WARNING: doxygen integration (breathe) will be
+# missing, so building from scratch will print a LOT of warnings!
+# However this is very useful for small, drive-by .rst fixes.
+html-minimal:
+	${MAKE} html DT_TURBO_MODE=1 SPHINXOPTS='-t minimal ${SPHINXOPTS}'
+
+
 html latex pdf linkcheck doxygen: configure
 	cmake --build ${BUILDDIR} --target $@
 
diff --git a/doc/conf.py b/doc/conf.py
index 2545ffea54efb..604bcc6b35550 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -67,14 +67,12 @@
 # -- General configuration ------------------------------------------------
 
 extensions = [
-    "breathe",
     "sphinx.ext.todo",
     "sphinx.ext.extlinks",
     "sphinx.ext.autodoc",
     "sphinx.ext.graphviz",
     "zephyr.application",
     "zephyr.html_redirects",
-    "zephyr.kconfig",
     "zephyr.dtcompatible-role",
     "zephyr.link-roles",
     "sphinx_tabs.tabs",
@@ -86,6 +84,14 @@
     "zephyr.external_content",
 ]
 
+# List of semi-optional features that make the incremental build
+# and/or the build from scratch significantly slower.
+if not tags.has("minimal"):  # pylint: disable=undefined-variable
+    extensions += [
+        "breathe",
+        "zephyr.kconfig",
+    ]
+
 # Only use SVG converter when it is really needed, e.g. LaTeX.
 if tags.has("svgconvert"):  # pylint: disable=undefined-variable
     extensions.append("sphinxcontrib.rsvgconverter")