doc: add make html-live and html-live-fast

Add two new commands that automatically locally host the generated
documentation upon completion and rebuild/rehost when the input files
change without any user interaction.

For more info see: https://pypi.org/project/sphinx-autobuild/

Signed-off-by: Jordan Yates <jordan@embeint.com>

doc/CMakeLists.txt

@@ -32,6 +32,7 @@ find_program(SPHINXBUILD sphinx-build)
 if(NOT SPHINXBUILD)
   message(FATAL_ERROR "The 'sphinx-build' command was not found")
 endif()
+find_program(SPHINXAUTOBUILD sphinx-autobuild)
 
 find_package(LATEX COMPONENTS PDFLATEX)
 find_program(LATEXMK latexmk)
@@ -173,6 +174,35 @@ set_target_properties(
 
 add_dependencies(html devicetree)
 
+#-------------------------------------------------------------------------------
+# html-live
+
+add_doc_target(
+  html-live
+  COMMAND ${CMAKE_COMMAND} -E env ${SPHINX_ENV}
+  ${SPHINXAUTOBUILD}
+    --watch ${DOCS_CFG_DIR}
+    --ignore ${DOCS_BUILD_DIR}
+    -b html
+    -c ${DOCS_CFG_DIR}
+    -d ${DOCS_DOCTREE_DIR}
+    -w ${DOCS_BUILD_DIR}/html.log
+    -t ${DOC_TAG}
+    ${SPHINXOPTS}
+    ${SPHINXOPTS_EXTRA}
+    ${DOCS_SRC_DIR}
+    ${DOCS_HTML_DIR}
+  USES_TERMINAL
+  COMMENT "Running Sphinx HTML autobuild..."
+)
+
+set_target_properties(
+  html-live html-live-nodeps
+  PROPERTIES
+    ADDITIONAL_CLEAN_FILES "${DOCS_SRC_DIR};${DOCS_HTML_DIR};${DOCS_DOCTREE_DIR}"
+)
+
+add_dependencies(html-live devicetree)
 #-------------------------------------------------------------------------------
 # pdf
 

doc/Makefile

@@ -12,12 +12,15 @@ DT_TURBO_MODE ?= 0
 # ------------------------------------------------------------------------------
 # Documentation targets
 
-.PHONY: configure clean html html-fast latex pdf doxygen
+.PHONY: configure clean html html-fast html-live html-live-fast latex pdf doxygen
 
 html-fast:
 	${MAKE} html DT_TURBO_MODE=1
 
-html latex pdf linkcheck doxygen: configure
+html-live-fast:
+	${MAKE} html-live DT_TURBO_MODE=1
+
+html html-live latex pdf linkcheck doxygen: configure
 	cmake --build ${BUILDDIR} --target $@
 
 configure:

doc/contribute/documentation/generation.rst

@@ -279,6 +279,12 @@ with a web browser:
 
       $ python3 -m http.server -d _build/html --bind 127.0.0.1
 
+Alternatively, the documentation can be built with the ``make html-live``
+(or ``make html-live-fast``) command, which will build the documentation, host
+it locally, and watch the documentation directory for changes. When changes are
+observed, it will automatically rebuild the documentation and refresh the hosted
+files.
+
 Linking external Doxygen projects against Zephyr
 ************************************************
 

doc/releases/release-notes-4.0.rst

@@ -97,6 +97,13 @@ Boards & SoC Support
 Build system and Infrastructure
 *******************************
 
+Documentation
+*************
+
+ * Added two new build commands, ``make html-live`` and ``make html-live-fast``, that automatically locally
+   host the generated documentation. They also automatically rebuild and rehost the documentation when changes
+   to the input ``.rst`` files are detected on the filesystem.
+
 Drivers and Sensors
 *******************
 

doc/requirements.txt

@@ -9,6 +9,7 @@ sphinx-notfound-page
 sphinx-copybutton
 sphinx-togglebutton
 sphinx-sitemap
+sphinx-autobuild
 
 # YAML validation. Used by zephyr_module.
 PyYAML>=6.0