doc: turbo mode for kconfig options

Building the documentation for all the Kconfig options significantly
adds to the total doc build time.  When making and testing major changes
to the documentation, we provide an option to temporarily stub-out
the auto-generated configuration documentation so the doc build process
runs much faster.

To enable this mode, set the following option when invoking cmake

    -DKCONFIG_TURBO_MODE=1

Signed-off-by: Anas Nashif <anas.nashif@intel.com>

Makefile

@@ -15,5 +15,8 @@ SPHINXOPTS ?= -q
 htmldocs:
 	mkdir -p ${BUILDDIR} && cmake -GNinja -DDOC_TAG=${DOC_TAG} -DSPHINXOPTS=${SPHINXOPTS} -B${BUILDDIR} -Hdoc/ && ninja -C ${BUILDDIR} htmldocs
 
+htmldocs-fast:
+	mkdir -p ${BUILDDIR} && cmake -GNinja -DKCONFIG_TURBO_MODE=1 -DDOC_TAG=${DOC_TAG} -DSPHINXOPTS=${SPHINXOPTS} -B${BUILDDIR} -Hdoc/ && ninja -C ${BUILDDIR} htmldocs
+
 pdfdocs:
 	mkdir -p ${BUILDDIR} && cmake -GNinja -DDOC_TAG=${DOC_TAG} -DSPHINXOPTS=${SPHINXOPTS} -B${BUILDDIR} -Hdoc/ && ninja -C ${BUILDDIR} pdfdocs

doc/CMakeLists.txt

@@ -144,6 +144,7 @@ add_custom_target(
   ARCH=*
   SOC_DIR=soc/
   SRCARCH=x86
+  KCONFIG_TURBO_MODE=${KCONFIG_TURBO_MODE}
   ${PYTHON_EXECUTABLE} scripts/genrest.py Kconfig ${RST_OUT}/doc/reference/kconfig/
   WORKING_DIRECTORY ${CMAKE_CURRENT_LIST_DIR}
 )

doc/README.rst

@@ -212,6 +212,28 @@ them out as "expected" warnings by adding a conf file to the
 ``.known-issues/doc`` folder, following the example of other conf files
 found there.
 
+Developer-mode Document Building
+********************************
+
+Building the documentation for all the Kconfig options significantly
+adds to the total doc build time.  When making and testing major changes
+to the documentation, we provide an option to temporarily stub-out
+the auto-generated configuration documentation so the doc build process
+runs much faster.
+
+To enable this mode, set the following option when invoking cmake::
+
+   -DKCONFIG_TURBO_MODE=1
+
+or invoke make with the following target::
+
+   cd ~/zephyr
+   source zephyr-env.sh
+
+   # To generate HTML output without detailed Kconfig
+   make htmldocs-fast
+
+
 .. _reStructuredText: http://sphinx-doc.org/rest.html
 .. _Sphinx: http://sphinx-doc.org/
 .. _Windows Python Path: https://docs.python.org/3/using/windows.html#finding-the-python-executable

doc/scripts/genrest.py

@@ -80,6 +80,9 @@ def expr_str(expr):
 def write_kconfig_rst():
     # The "main" function. Writes index.rst and the symbol RST files.
 
+    # accelerate doc building by skipping kconfig option documentation.
+    turbo_mode = os.environ.get('KCONFIG_TURBO_MODE') == "1"
+
     if len(sys.argv) != 3:
         print("usage: {} <Kconfig> <output directory>", file=sys.stderr)
         sys.exit(1)
@@ -89,11 +92,15 @@ def write_kconfig_rst():
 
     # String with the RST for the index page
     index_rst = INDEX_RST_HEADER
+    index_def_rst = ":orphan:\n\n"
 
     # Sort the symbols by name so that they end up in sorted order in index.rst
     for sym in sorted(kconf.unique_defined_syms, key=lambda sym: sym.name):
-        # Write an RST file for the symbol
-        write_sym_rst(sym, out_dir)
+        if turbo_mode:
+            index_def_rst += ".. option:: CONFIG_{}\n".format(sym.name)
+        else:
+            # Write an RST file for the symbol
+            write_sym_rst(sym, out_dir)
 
         # Add an index entry for the symbol that links to its RST file. Also
         # list its prompt(s), if any. (A symbol can have multiple prompts if it
@@ -103,9 +110,12 @@ def write_kconfig_rst():
             " / ".join(node.prompt[0]
                        for node in sym.nodes if node.prompt))
 
-    for choice in kconf.unique_choices:
-        # Write an RST file for the choice
-        write_choice_rst(choice, out_dir)
+    if turbo_mode:
+        write_if_updated(os.path.join(out_dir, "options.rst"), index_def_rst)
+    else:
+        for choice in kconf.unique_choices:
+            # Write an RST file for the choice
+            write_choice_rst(choice, out_dir)
 
     write_if_updated(os.path.join(out_dir, "index.rst"), index_rst)