doc: CMakeLists.txt: do not require sphinx

There are several doc-related build targets that do not require sphinx, e.g. one might want to simply generate the Doxygen docs (Doxygen remaining a hard dependency), so do not require sphinx to be present and, instead, conditionally add the associated targets when sphinx is present. Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
2025-09-16 09:50:15 +02:00
parent 61a9d6aa45
commit b1a74d75e8
1 changed files with 101 additions and 93 deletions
--- a/doc/CMakeLists.txt
+++ b/doc/CMakeLists.txt
@@ -32,7 +32,7 @@ find_package(Doxygen REQUIRED dot)

 find_program(SPHINXBUILD sphinx-build)
 if(NOT SPHINXBUILD)
-  message(FATAL_ERROR "The 'sphinx-build' command was not found")
+  message(WARNING "The 'sphinx-build' command was not found; Sphinx-based targets will not be available.")
 endif()
 find_program(SPHINXAUTOBUILD sphinx-autobuild)

@@ -187,90 +187,96 @@ if(HW_FEATURES_VENDOR_FILTER)
  list(APPEND SPHINXOPTS "-D" "zephyr_hw_features_vendor_filter=${vendor_filter}")
 endif()

-add_doc_target(
-  html
-  COMMAND ${CMAKE_COMMAND} -E env ${SPHINX_ENV} OUTPUT_DIR=${DOCS_HTML_DIR}
-  ${SPHINXBUILD}
-    -b html
-    -c ${DOCS_CFG_DIR}
-    -d ${DOCS_DOCTREE_DIR}
-    -w ${DOCS_BUILD_DIR}/html.log
-    ${SPHINX_TAGS_ARGS}
-    ${SPHINXOPTS}
-    ${SPHINXOPTS_EXTRA}
-    ${DOCS_SRC_DIR}
-    ${DOCS_HTML_DIR}
-  USES_TERMINAL
-  COMMENT "Running Sphinx HTML build..."
-)
+if(SPHINXBUILD)
+  add_doc_target(
+    html
+    COMMAND ${CMAKE_COMMAND} -E env ${SPHINX_ENV} OUTPUT_DIR=${DOCS_HTML_DIR}
+    ${SPHINXBUILD}
+      -b html
+      -c ${DOCS_CFG_DIR}
+      -d ${DOCS_DOCTREE_DIR}
+      -w ${DOCS_BUILD_DIR}/html.log
+      ${SPHINX_TAGS_ARGS}
+      ${SPHINXOPTS}
+      ${SPHINXOPTS_EXTRA}
+      ${DOCS_SRC_DIR}
+      ${DOCS_HTML_DIR}
+    USES_TERMINAL
+    COMMENT "Running Sphinx HTML build..."
+  )

-set_target_properties(
-  html html-nodeps
-  PROPERTIES
-    ADDITIONAL_CLEAN_FILES "${DOCS_SRC_DIR};${DOCS_HTML_DIR};${DOCS_DOCTREE_DIR}"
-)
+  set_target_properties(
+    html html-nodeps
+    PROPERTIES
+      ADDITIONAL_CLEAN_FILES "${DOCS_SRC_DIR};${DOCS_HTML_DIR};${DOCS_DOCTREE_DIR}"
+  )

-add_dependencies(html devicetree)
+  add_dependencies(html devicetree)
+endif()

 #-------------------------------------------------------------------------------
 # html-live

-add_doc_target(
-  html-live
-  COMMAND ${CMAKE_COMMAND} -E env ${SPHINX_ENV} OUTPUT_DIR=${DOCS_HTML_DIR}
-  ${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
-    ${SPHINX_TAGS_ARGS}
-    ${SPHINXOPTS}
-    ${SPHINXOPTS_EXTRA}
-    ${DOCS_SRC_DIR}
-    ${DOCS_HTML_DIR}
-  USES_TERMINAL
-  COMMENT "Running Sphinx HTML autobuild..."
-)
+if(SPHINXBUILD)
+  add_doc_target(
+    html-live
+    COMMAND ${CMAKE_COMMAND} -E env ${SPHINX_ENV} OUTPUT_DIR=${DOCS_HTML_DIR}
+    ${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
+      ${SPHINX_TAGS_ARGS}
+      ${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}"
-)
+  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)
+  add_dependencies(html-live devicetree)
+endif()
 #-------------------------------------------------------------------------------
 # pdf

-add_doc_target(
-  latex
-  COMMAND ${CMAKE_COMMAND} -E env ${SPHINX_ENV} OUTPUT_DIR=${DOCS_LATEX_DIR}
-  ${SPHINXBUILD}
-    -b latex
-    -c ${DOCS_CFG_DIR}
-    -d ${DOCS_DOCTREE_DIR}
-    -w ${DOCS_BUILD_DIR}/latex.log
-    ${SPHINX_TAGS_ARGS}
-    -t convertimages
-    ${SPHINXOPTS}
-    ${SPHINXOPTS_EXTRA}
-    ${DOCS_SRC_DIR}
-    ${DOCS_LATEX_DIR}
-  USES_TERMINAL
-  COMMENT "Running Sphinx LaTeX build..."
-)
+if(SPHINXBUILD)
+  add_doc_target(
+    latex
+    COMMAND ${CMAKE_COMMAND} -E env ${SPHINX_ENV} OUTPUT_DIR=${DOCS_LATEX_DIR}
+    ${SPHINXBUILD}
+      -b latex
+      -c ${DOCS_CFG_DIR}
+      -d ${DOCS_DOCTREE_DIR}
+      -w ${DOCS_BUILD_DIR}/latex.log
+      ${SPHINX_TAGS_ARGS}
+      -t convertimages
+      ${SPHINXOPTS}
+      ${SPHINXOPTS_EXTRA}
+      ${DOCS_SRC_DIR}
+      ${DOCS_LATEX_DIR}
+    USES_TERMINAL
+    COMMENT "Running Sphinx LaTeX build..."
+  )

-set_target_properties(
-  latex latex-nodeps
-  PROPERTIES
-    ADDITIONAL_CLEAN_FILES "${DOCS_SRC_DIR};${DOCS_LATEX_DIR};${DOCS_DOCTREE_DIR}"
-)
+  set_target_properties(
+    latex latex-nodeps
+    PROPERTIES
+      ADDITIONAL_CLEAN_FILES "${DOCS_SRC_DIR};${DOCS_LATEX_DIR};${DOCS_DOCTREE_DIR}"
+  )

-add_dependencies(latex devicetree)
+  add_dependencies(latex devicetree)
+endif()

-if(LATEX_PDFLATEX_FOUND AND LATEXMK)
+if(SPHINXBUILD AND LATEX_PDFLATEX_FOUND AND LATEXMK)
  if(WIN32)
    set(PDF_BUILD_COMMAND "make.bat")
  else()
@@ -296,30 +302,32 @@ endif()
 #-------------------------------------------------------------------------------
 # linkcheck

-add_doc_target(
-  linkcheck
-  COMMAND ${CMAKE_COMMAND} -E env ${SPHINX_ENV} OUTPUT_DIR=${DOCS_LINKCHECK_DIR}
-  ${SPHINXBUILD}
-    -b linkcheck
-    -c ${DOCS_CFG_DIR}
-    -d ${DOCS_DOCTREE_DIR}
-    -w ${DOCS_BUILD_DIR}/linkcheck.log
-    ${SPHINX_TAGS_ARGS}
-    ${SPHINXOPTS}
-    ${SPHINXOPTS_EXTRA}
-    ${DOCS_SRC_DIR}
-    ${DOCS_LINKCHECK_DIR}
-  USES_TERMINAL
-  COMMENT "Running Sphinx link check..."
-)
+if(SPHINXBUILD)
+  add_doc_target(
+    linkcheck
+    COMMAND ${CMAKE_COMMAND} -E env ${SPHINX_ENV} OUTPUT_DIR=${DOCS_LINKCHECK_DIR}
+    ${SPHINXBUILD}
+      -b linkcheck
+      -c ${DOCS_CFG_DIR}
+      -d ${DOCS_DOCTREE_DIR}
+      -w ${DOCS_BUILD_DIR}/linkcheck.log
+      ${SPHINX_TAGS_ARGS}
+      ${SPHINXOPTS}
+      ${SPHINXOPTS_EXTRA}
+      ${DOCS_SRC_DIR}
+      ${DOCS_LINKCHECK_DIR}
+    USES_TERMINAL
+    COMMENT "Running Sphinx link check..."
+  )

-set_target_properties(
-  linkcheck linkcheck-nodeps
-  PROPERTIES
-    ADDITIONAL_CLEAN_FILES "${DOCS_SRC_DIR};${DOCS_LINKCHECK_DIR};${DOCS_DOCTREE_DIR}"
-)
+  set_target_properties(
+    linkcheck linkcheck-nodeps
+    PROPERTIES
+      ADDITIONAL_CLEAN_FILES "${DOCS_SRC_DIR};${DOCS_LINKCHECK_DIR};${DOCS_DOCTREE_DIR}"
+  )

-add_dependencies(linkcheck devicetree)
+  add_dependencies(linkcheck devicetree)
+endif()

 #-------------------------------------------------------------------------------
 # others