patrick/zephyr
1
0
Fork 0
Code Issues Pull requests Actions 7 Packages Projects Releases Wiki Activity

doc: add sphinx-html and sphinx-latex convenience targets

Browse source 
Most of time (i.e. when just writing to .rst files or editing images,
rather than editing Doxygen or Kconfig), a full rebuild of the docs
pipeline is not necessary.

This is unfortunate, because it takes over a minute to re-run doxygen
etc. (on my system), whereas an incremental sphinx-build run should
only take a few seconds.

As a band-aid to help developers who have already generated a docs
build and know the consequences of their actions, add "sphinx-html"
and "sphinx-latex" targets. These just re-extract content files into
the build directory and run sphinx-build. This makes for much faster
documentation edit/compile/read loops.

Add some extra COMMENTs while we're here, to make it more obvious
what's going on when the docs build system crunches on something.

A "proper" solution for changing "ninja html" to have similar
performance would need, at least, to:

- only re-run doxygen if any source files have changed
- only re-generate Kconfig if any of those files have changed

That's all left to future work, as this is good enough to make
rebuilding the docs bearable for me.

Signed-off-by: Marti Bolivar <marti@foundries.io>
This commit is contained in:
Marti Bolivar 2018-10-09 14:24:34 -06:00 committed by Carles Cufí
parent 2952bf85d9
commit d9f512cbcf
1 changed files with 38 additions and 6 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

44
doc/CMakeLists.txt
View file

@ -186,31 +186,62 @@ set(CONFIG_DIR ${ZEPHYR_BASE}/.known-issues/doc)
#
# HTML section
#
set(SPHINX_BUILD_HTML_COMMAND
${CMAKE_COMMAND} -E env
ZEPHYR_BUILD=${CMAKE_CURRENT_BINARY_DIR}
${SPHINXBUILD} -w ${SPHINX_LOG} -N -t ${DOC_TAG} -b html ${ALLSPHINXOPTS} ${RST_OUT}/doc ${SPHINX_OUTPUT_DIR_HTML})
# The sphinx-html target is provided as a convenience for incremental
# re-builds of content files without regenerating the entire docs
# pipeline. It can be significantly faster than re-running the full
# HTML build, but it has no idea if Doxygen, Kconfig, etc. need to be
# regenerated. Use with caution.
add_custom_target(
sphinx-html
COMMAND ${SPHINX_BUILD_HTML_COMMAND}
DEPENDS ${EXTRACT_CONTENT_OUTPUTS}
COMMENT "Just re-generating HTML (USE WITH CAUTION)"
USES_TERMINAL
)
add_custom_target(
html
COMMAND ${CMAKE_COMMAND} -E env
ZEPHYR_BUILD=${CMAKE_CURRENT_BINARY_DIR}
${SPHINXBUILD} -w ${SPHINX_LOG} -N -t ${DOC_TAG} -b html ${ALLSPHINXOPTS} ${RST_OUT}/doc ${SPHINX_OUTPUT_DIR_HTML}
COMMAND ${SPHINX_BUILD_HTML_COMMAND}
# Merge the Doxygen and Sphinx logs into a single file
COMMAND ${CMAKE_COMMAND} -P ${ZEPHYR_BASE}/cmake/util/fmerge.cmake ${DOC_LOG} ${DOXY_LOG} ${SPHINX_LOG}
COMMAND ${PYTHON_EXECUTABLE} ${KI_SCRIPT} --config-dir ${CONFIG_DIR} --errors ${DOC_WARN} --warnings ${DOC_WARN} ${DOC_LOG}
WORKING_DIRECTORY ${CMAKE_CURRENT_LIST_DIR}
COMMENT "Generating HTML documentation"
${SPHINX_USES_TERMINAL}
)
#
# LaTEX section
#
set(SPHINX_BUILD_LATEX_COMMAND
${CMAKE_COMMAND} -E env
ZEPHYR_BUILD=${CMAKE_CURRENT_BINARY_DIR}
${SPHINXBUILD} -w ${SPHINX_LOG} -N -t ${DOC_TAG} -b latex -t svgconvert ${ALLSPHINXOPTS} ${RST_OUT}/doc ${SPHINX_OUTPUT_DIR_LATEX})
# The sphinx-latex target works similarly to sphinx-html, and carries
# the same warnings.
add_custom_target(
sphinx-latex
COMMAND ${SPHINX_BUILD_LATEX_COMMAND}
DEPENDS ${EXTRACT_CONTENT_OUTPUTS}
COMMENT "Just re-generating LaTeX (USE WITH CAUTION)"
USES_TERMINAL
)
add_custom_command(
OUTPUT ${SPHINX_OUTPUT_DIR_LATEX}/zephyr.tex
COMMAND ${CMAKE_COMMAND} -E env
ZEPHYR_BUILD=${CMAKE_CURRENT_BINARY_DIR}
${SPHINXBUILD} -w ${SPHINX_LOG} -N -t ${DOC_TAG} -b latex -t svgconvert ${ALLSPHINXOPTS} ${RST_OUT}/doc ${SPHINX_OUTPUT_DIR_LATEX}
COMMAND ${SPHINX_BUILD_LATEX_COMMAND}
# Merge the Doxygen and Sphinx logs into a single file
COMMAND ${CMAKE_COMMAND} -P ${ZEPHYR_BASE}/cmake/util/fmerge.cmake ${DOC_LOG} ${DOXY_LOG} ${SPHINX_LOG}
COMMAND ${PYTHON_EXECUTABLE} ${KI_SCRIPT} --config-dir ${CONFIG_DIR} --errors ${DOC_WARN} --warnings ${DOC_WARN} ${DOC_LOG}
COMMAND ${PYTHON_EXECUTABLE} ${FIX_TEX_SCRIPT} ${SPHINX_OUTPUT_DIR_LATEX}/zephyr.tex
WORKING_DIRECTORY ${CMAKE_CURRENT_LIST_DIR}
COMMENT "Generating LaTeX documentation"
${SPHINX_USES_TERMINAL}
)
@ -231,6 +262,7 @@ add_custom_command(
LATEXOPTS="-halt-on-error -no-shell-escape"
${LATEXMK} -quiet -pdf -dvi- -ps-
WORKING_DIRECTORY ${SPHINX_OUTPUT_DIR_LATEX}
COMMENT "Generating PDF documentation"
)
if(NOT DEFINED SPHINX_OUTPUT_DIR)