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:
parent
2e99de8047
commit
2f143fb2c1
5 changed files with 49 additions and 2 deletions
|
@ -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
|
||||
|
||||
|
|
|
@ -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:
|
||||
|
|
|
@ -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
|
||||
************************************************
|
||||
|
||||
|
|
|
@ -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
|
||||
*******************
|
||||
|
||||
|
|
|
@ -9,6 +9,7 @@ sphinx-notfound-page
|
|||
sphinx-copybutton
|
||||
sphinx-togglebutton
|
||||
sphinx-sitemap
|
||||
sphinx-autobuild
|
||||
|
||||
# YAML validation. Used by zephyr_module.
|
||||
PyYAML>=6.0
|
||||
|
|
Loading…
Add table
Add a link
Reference in a new issue