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>
This commit is contained in:
Jordan Yates 2024-05-11 12:07:11 +10:00 committed by Carles Cufí
commit 2f143fb2c1
5 changed files with 49 additions and 2 deletions

View file

@ -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

View file

@ -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:

View file

@ -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
************************************************

View file

@ -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
*******************

View file

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