doc: add support for linkcheck

This patch adds support for the `linkcheck` Sphinx builder, so that we
can easily check for broken links in the documentation.

It can be run like this:

ninja linkcheck

Or, using the Makefile shim:

make linkcheck

All Zephyr Github issues links are ignored, since we have lots of these
URLs and they quickly hit GH rate limit. They have small chance to be
incorrect, so we should be ok.

Signed-off-by: Gerard Marull-Paretas <[email protected]>

Author: gmarull

doc/CMakeLists.txt

@@ -49,6 +49,7 @@ set(DOCS_DOCTREE_DIR ${CMAKE_CURRENT_BINARY_DIR}/doctrees)
 set(DOCS_BUILD_DIR ${CMAKE_CURRENT_BINARY_DIR})
 set(DOCS_SRC_DIR ${CMAKE_CURRENT_BINARY_DIR}/src)
 set(DOCS_HTML_DIR ${CMAKE_CURRENT_BINARY_DIR}/html)
+set(DOCS_LINKCHECK_DIR ${CMAKE_CURRENT_BINARY_DIR}/linkcheck)
 set(DOCS_LATEX_DIR ${CMAKE_CURRENT_BINARY_DIR}/latex)
 
 if(WIN32)
@@ -208,6 +209,33 @@ if(LATEX_PDFLATEX_FOUND AND LATEXMK)
   add_dependencies(pdf latex)
 endif()
 
+#-------------------------------------------------------------------------------
+# linkcheck
+
+add_doc_target(
+  linkcheck
+  COMMAND ${CMAKE_COMMAND} -E env ${SPHINX_ENV}
+  ${SPHINXBUILD}
+    -b linkcheck
+    -c ${DOCS_CFG_DIR}
+    -d ${DOCS_DOCTREE_DIR}
+    -w ${DOCS_BUILD_DIR}/linkcheck.log
+    -t ${DOC_TAG}
+    ${SPHINXOPTS}
+    ${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}"
+)
+
+add_dependencies(linkcheck devicetree)
+
 #-------------------------------------------------------------------------------
 # others
 

doc/Makefile

@@ -16,7 +16,7 @@ DT_TURBO_MODE ?= 0
 html-fast:
 	${MAKE} html DT_TURBO_MODE=1
 
-html latex pdf doxygen: configure
+html latex pdf linkcheck doxygen: configure
 	cmake --build ${BUILDDIR} --target $@
 
 configure:

doc/conf.py

@@ -201,6 +201,12 @@
     ("index-tex", "zephyr.tex", "Zephyr Project Documentation", author, "manual"),
 ]
 
+# -- Options for linkcheck ------------------------------------------------
+
+linkcheck_ignore = [
+    r"https://github.com/zephyrproject-rtos/zephyr/issues/.*"
+]
+
 # -- Options for zephyr.doxyrunner plugin ---------------------------------
 
 doxyrunner_doxygen = os.environ.get("DOXYGEN_EXECUTABLE", "doxygen")