From 2f143fb2c1366aaea9697ad2ed2becd304e0f897 Mon Sep 17 00:00:00 2001
From: Jordan Yates <jordan@embeint.com>
Date: Sat, 11 May 2024 12:07:11 +1000
Subject: [PATCH] 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                          | 30 +++++++++++++++++++++
 doc/Makefile                                |  7 +++--
 doc/contribute/documentation/generation.rst |  6 +++++
 doc/releases/release-notes-4.0.rst          |  7 +++++
 doc/requirements.txt                        |  1 +
 5 files changed, 49 insertions(+), 2 deletions(-)

diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt
index 826376cc3aa..904ce96a6ac 100644
--- a/doc/CMakeLists.txt
+++ b/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
 
diff --git a/doc/Makefile b/doc/Makefile
index 321a1b92cc4..e1dd82d59cb 100644
--- a/doc/Makefile
+++ b/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:
diff --git a/doc/contribute/documentation/generation.rst b/doc/contribute/documentation/generation.rst
index 013decd0455..69b12bd7ed6 100644
--- a/doc/contribute/documentation/generation.rst
+++ b/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
 ************************************************
 
diff --git a/doc/releases/release-notes-4.0.rst b/doc/releases/release-notes-4.0.rst
index cbf97b7fa5a..e69accac6db 100644
--- a/doc/releases/release-notes-4.0.rst
+++ b/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
 *******************
 
diff --git a/doc/requirements.txt b/doc/requirements.txt
index 468be6969c1..aa77efa604f 100644
--- a/doc/requirements.txt
+++ b/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