1# SPDX-License-Identifier: Apache-2.0
2
3cmake_minimum_required(VERSION 3.20.0)
4project(Zephyr-Kernel-Doc LANGUAGES)
5
6set(MIN_WEST_VERSION 1.0.0)
7find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE} .. COMPONENTS doc)
8
9file(TO_CMAKE_PATH "${ZEPHYR_BASE}" ZEPHYR_BASE)
10message(STATUS "Zephyr base: ${ZEPHYR_BASE}")
11
12#-------------------------------------------------------------------------------
13# Options
14
15set(SPHINXOPTS "-j auto -W --keep-going -T" CACHE STRING "Default Sphinx Options")
16set(SPHINXOPTS_EXTRA "" CACHE STRING "Extra Sphinx Options (added to defaults)")
17set(LATEXMKOPTS "-halt-on-error -no-shell-escape" CACHE STRING "Default latexmk options")
18set(DT_TURBO_MODE OFF CACHE BOOL "Enable DT turbo mode")
19set(DOC_TAG "development" CACHE STRING "Documentation tag")
20set(DTS_ROOTS "${ZEPHYR_BASE}" CACHE STRING "DT bindings root folders")
21
22separate_arguments(SPHINXOPTS)
23separate_arguments(SPHINXOPTS_EXTRA)
24separate_arguments(LATEXMKOPTS)
25
26#-------------------------------------------------------------------------------
27# Dependencies
28
29find_package(Doxygen REQUIRED dot)
30
31find_program(SPHINXBUILD sphinx-build)
32if(NOT SPHINXBUILD)
33  message(FATAL_ERROR "The 'sphinx-build' command was not found")
34endif()
35
36find_package(LATEX COMPONENTS PDFLATEX)
37find_program(LATEXMK latexmk)
38if(NOT LATEX_PDFLATEX_FOUND OR NOT LATEXMK)
39  message(WARNING "LaTeX components not found. PDF build will not be available.")
40endif()
41
42#-------------------------------------------------------------------------------
43# Environment & Paths
44
45set(SPHINX_ENV
46  DOXYGEN_EXECUTABLE=${DOXYGEN_EXECUTABLE}
47  DOT_EXECUTABLE=${DOXYGEN_DOT_EXECUTABLE}
48)
49
50if(DEFINED ENV{ZEPHYR_DOXYGEN_OVERLAY})
51  if(EXISTS $ENV{ZEPHYR_DOXYGEN_OVERLAY})
52    set(INCLUDE_CUSTOM_FILE "@INCLUDE = $ENV{ZEPHYR_DOXYGEN_OVERLAY}")
53  else()
54    message(FATAL_ERROR "Zephyr Doxygen overlay $ENV{ZEPHYR_DOXYGEN_OVERLAY} does not exist!")
55  endif()
56else()
57  set(INCLUDE_CUSTOM_FILE "")
58endif()
59
60set(DOCS_CFG_DIR ${CMAKE_CURRENT_LIST_DIR})
61set(DOCS_DOCTREE_DIR ${CMAKE_CURRENT_BINARY_DIR}/doctrees)
62set(DOCS_BUILD_DIR ${CMAKE_CURRENT_BINARY_DIR})
63set(DOCS_SRC_DIR ${CMAKE_CURRENT_BINARY_DIR}/src)
64set(DOCS_HTML_DIR ${CMAKE_CURRENT_BINARY_DIR}/html)
65set(DOCS_LINKCHECK_DIR ${CMAKE_CURRENT_BINARY_DIR}/linkcheck)
66set(DOCS_LATEX_DIR ${CMAKE_CURRENT_BINARY_DIR}/latex)
67
68if(WIN32)
69  set(SEP $<SEMICOLON>)
70else()
71  set(SEP :)
72endif()
73
74#-------------------------------------------------------------------------------
75# Functions
76
77# Create a custom doc target.
78#
79# This function has the same signature as `add_custom_target()`
80#
81# The function will create two targets for the doc build system.
82# - Target 1 named: `<name>`
83# - Target 2 named: `<name>-nodeps`
84#
85# Both targets will produce same result, but target 2 must have no dependencies.
86# This is useful to, e.g. re-run the Sphinx build without dependencies such as
87# devicetree generator.
88#
89function(add_doc_target name)
90  add_custom_target(${name} ${ARGN})
91  add_custom_target(${name}-nodeps ${ARGN})
92endfunction()
93
94#-------------------------------------------------------------------------------
95# Doxygen (standalone)
96
97set(DOXY_OUT ${CMAKE_CURRENT_BINARY_DIR}/doxygen)
98set(DOXYFILE_IN ${CMAKE_CURRENT_LIST_DIR}/zephyr.doxyfile.in)
99set(DOXYFILE_OUT ${CMAKE_CURRENT_BINARY_DIR}/zephyr.doxyfile)
100set(ZEPHYR_VERSION "${Zephyr_VERSION}")
101
102configure_file(${DOXYFILE_IN} ${DOXYFILE_OUT} @ONLY)
103
104add_custom_target(
105  doxygen
106  COMMAND
107    ${DOXYGEN_EXECUTABLE} ${DOXYFILE_OUT}
108  COMMENT "Running Doxygen..."
109)
110
111set_target_properties(
112  doxygen
113  PROPERTIES
114    ADDITIONAL_CLEAN_FILES "${DOXY_OUT}"
115)
116
117#-------------------------------------------------------------------------------
118# devicetree
119
120set(GEN_DEVICETREE_REST_SCRIPT ${CMAKE_CURRENT_LIST_DIR}/_scripts/gen_devicetree_rest.py)
121
122set(DTS_ARGS)
123foreach(root ${DTS_ROOTS})
124  list(APPEND DTS_ARGS --dts-root ${root})
125endforeach()
126
127if(DT_TURBO_MODE)
128  list(APPEND DTS_ARGS --turbo-mode)
129endif()
130
131add_custom_target(
132  devicetree
133  COMMAND ${CMAKE_COMMAND} -E env
134  PYTHONPATH=${ZEPHYR_BASE}/scripts/dts/python-devicetree/src${SEP}$ENV{PYTHONPATH}
135  ZEPHYR_BASE=${ZEPHYR_BASE}
136  ${PYTHON_EXECUTABLE} ${GEN_DEVICETREE_REST_SCRIPT}
137    --vendor-prefixes ${ZEPHYR_BASE}/dts/bindings/vendor-prefixes.txt
138    ${DTS_ARGS}
139    ${DOCS_SRC_DIR}/build/dts/api
140  VERBATIM
141  USES_TERMINAL
142  COMMENT "Generating Devicetree bindings documentation..."
143)
144
145set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS ${GEN_DEVICETREE_REST_SCRIPT})
146
147#-------------------------------------------------------------------------------
148# html
149
150add_doc_target(
151  html
152  COMMAND ${CMAKE_COMMAND} -E env ${SPHINX_ENV}
153  ${SPHINXBUILD}
154    -b html
155    -c ${DOCS_CFG_DIR}
156    -d ${DOCS_DOCTREE_DIR}
157    -w ${DOCS_BUILD_DIR}/html.log
158    -t ${DOC_TAG}
159    ${SPHINXOPTS}
160    ${SPHINXOPTS_EXTRA}
161    ${DOCS_SRC_DIR}
162    ${DOCS_HTML_DIR}
163  USES_TERMINAL
164  COMMENT "Running Sphinx HTML build..."
165)
166
167set_target_properties(
168  html html-nodeps
169  PROPERTIES
170    ADDITIONAL_CLEAN_FILES "${DOCS_SRC_DIR};${DOCS_HTML_DIR};${DOCS_DOCTREE_DIR}"
171)
172
173add_dependencies(html devicetree)
174
175#-------------------------------------------------------------------------------
176# pdf
177
178add_doc_target(
179  latex
180  COMMAND ${CMAKE_COMMAND} -E env ${SPHINX_ENV}
181  ${SPHINXBUILD}
182    -b latex
183    -c ${DOCS_CFG_DIR}
184    -d ${DOCS_DOCTREE_DIR}
185    -w ${DOCS_BUILD_DIR}/latex.log
186    -t ${DOC_TAG}
187    -t convertimages
188    ${SPHINXOPTS}
189    ${SPHINXOPTS_EXTRA}
190    ${DOCS_SRC_DIR}
191    ${DOCS_LATEX_DIR}
192  USES_TERMINAL
193  COMMENT "Running Sphinx LaTeX build..."
194)
195
196set_target_properties(
197  latex latex-nodeps
198  PROPERTIES
199    ADDITIONAL_CLEAN_FILES "${DOCS_SRC_DIR};${DOCS_LATEX_DIR};${DOCS_DOCTREE_DIR}"
200)
201
202add_dependencies(latex devicetree)
203
204if(LATEX_PDFLATEX_FOUND AND LATEXMK)
205  if(WIN32)
206    set(PDF_BUILD_COMMAND "make.bat")
207  else()
208    find_program(MAKE make)
209    if(NOT MAKE)
210      message(FATAL_ERROR "The 'make' command was not found")
211    endif()
212    set(PDF_BUILD_COMMAND ${MAKE})
213  endif()
214
215  add_custom_target(
216    pdf
217    COMMAND ${CMAKE_COMMAND} -E env LATEXMKOPTS="${LATEXMKOPTS}"
218    ${PDF_BUILD_COMMAND}
219    WORKING_DIRECTORY ${DOCS_LATEX_DIR}
220    COMMENT "Building PDF file..."
221    USES_TERMINAL
222  )
223
224  add_dependencies(pdf latex)
225endif()
226
227#-------------------------------------------------------------------------------
228# linkcheck
229
230add_doc_target(
231  linkcheck
232  COMMAND ${CMAKE_COMMAND} -E env ${SPHINX_ENV}
233  ${SPHINXBUILD}
234    -b linkcheck
235    -c ${DOCS_CFG_DIR}
236    -d ${DOCS_DOCTREE_DIR}
237    -w ${DOCS_BUILD_DIR}/linkcheck.log
238    -t ${DOC_TAG}
239    ${SPHINXOPTS}
240    ${SPHINXOPTS_EXTRA}
241    ${DOCS_SRC_DIR}
242    ${DOCS_LINKCHECK_DIR}
243  USES_TERMINAL
244  COMMENT "Running Sphinx link check..."
245)
246
247set_target_properties(
248  linkcheck linkcheck-nodeps
249  PROPERTIES
250    ADDITIONAL_CLEAN_FILES "${DOCS_SRC_DIR};${DOCS_LINKCHECK_DIR};${DOCS_DOCTREE_DIR}"
251)
252
253add_dependencies(linkcheck devicetree)
254
255#-------------------------------------------------------------------------------
256# others
257
258add_custom_target(
259  pristine
260  COMMAND ${CMAKE_COMMAND} -P ${ZEPHYR_BASE}/cmake/pristine.cmake
261)
262