blob: e666dc66e20bc975c7ba796104a8f0993f80c6c1 [file] [log] [blame]
Anas Nashif5060ca62018-12-11 10:33:23 -05001cmake_minimum_required(VERSION 3.13.1)
Sebastian Bøe5748fe12019-01-04 09:13:07 +01002project(Zephyr-Kernel-Doc LANGUAGES)
Carles Cufiae699342018-07-09 14:12:17 +02003
4set(ZEPHYR_BASE $ENV{ZEPHYR_BASE})
5
6message(STATUS "Zephyr base: ${ZEPHYR_BASE}")
7
Sebastian Bøe93230a52018-09-28 13:10:57 +02008include(${ZEPHYR_BASE}/cmake/version.cmake)
9
Carles Cufiae699342018-07-09 14:12:17 +020010find_package(PythonInterp 3.4)
11set(DOXYGEN_SKIP_DOT True)
12find_package(Doxygen REQUIRED)
Carles Cufi0698dba2018-10-02 10:30:39 +020013find_package(LATEX)
Carles Cufiae699342018-07-09 14:12:17 +020014
15find_program(
16 SPHINXBUILD
Marc Herberta49f9eb2019-02-04 15:24:01 -080017 NAMES sphinx-build-3 sphinx-build
Carles Cufiae699342018-07-09 14:12:17 +020018 )
19if(${SPHINXBUILD} STREQUAL SPHINXBUILD-NOTFOUND)
20 message(FATAL_ERROR "The 'sphinx-build' command was not found. Make sure you have Sphinx installed.")
21endif()
22
Daniel Leung9945e7f2018-08-23 11:11:11 -070023# Note that this won't force fatal error if latexmk is not found.
24# Not having LaTeX tools should not prevent people from generating HTML docs.
25find_program(
26 LATEXMK
27 latexmk
28 )
29if(${LATEXMK} STREQUAL LATEXMK-NOTFOUND)
30 message(WARNING "The 'latexmk' command was not found. Targets to build PDF will not be available.")
31endif()
32
Carles Cufiae699342018-07-09 14:12:17 +020033if(NOT DEFINED SPHINXOPTS)
34 set(SPHINXOPTS -q)
Carles Cufid505ca72018-07-13 12:37:13 +020035else()
36 separate_arguments(SPHINXOPTS)
Carles Cufiae699342018-07-09 14:12:17 +020037endif()
38
Carles Cufi896a6962018-08-16 13:45:59 +020039if(NOT DEFINED SPHINX_OUTPUT_DIR)
Daniel Leung9945e7f2018-08-23 11:11:11 -070040 set(SPHINX_OUTPUT_DIR_HTML ${CMAKE_CURRENT_BINARY_DIR}/html)
41 set(SPHINX_OUTPUT_DIR_LATEX ${CMAKE_CURRENT_BINARY_DIR}/latex)
42 set(SPHINX_OUTPUT_DIR_PDF ${CMAKE_CURRENT_BINARY_DIR}/pdf)
43else()
Marti Bolivar2952bf82018-10-09 13:28:41 -060044 # SPHINX_OUTPUT_DIR is used to specify exactly where HTML (or other
45 # outputs) are placed, so no /html, /latex, /pdf suffixes are needed.
Daniel Leung9945e7f2018-08-23 11:11:11 -070046 set(SPHINX_OUTPUT_DIR_HTML ${SPHINX_OUTPUT_DIR})
47 set(SPHINX_OUTPUT_DIR_LATEX ${SPHINX_OUTPUT_DIR})
48 set(SPHINX_OUTPUT_DIR_PDF ${SPHINX_OUTPUT_DIR})
Carles Cufi896a6962018-08-16 13:45:59 +020049endif()
50
Carles Cufiae699342018-07-09 14:12:17 +020051if(NOT DEFINED DOC_TAG)
52 set(DOC_TAG development)
53endif()
54
55# Internal variables.
Carles Cufi2af9a9e2018-07-13 15:32:36 +020056set(ALLSPHINXOPTS -d ${CMAKE_CURRENT_BINARY_DIR}/doctrees ${SPHINXOPTS})
Carles Cufi60c55402018-07-15 18:57:01 +020057if("-q" IN_LIST ALLSPHINXOPTS)
58 set(SPHINX_USES_TERMINAL )
59else()
60 set(SPHINX_USES_TERMINAL USES_TERMINAL)
61endif()
62
Carles Cufiae699342018-07-09 14:12:17 +020063# the i18n builder cannot share the environment and doctrees with the others
Carles Cufid505ca72018-07-13 12:37:13 +020064set(I18NSPHINXOPTS ${SPHINXOPTS})
Carles Cufiae699342018-07-09 14:12:17 +020065
Carles Cufie182dbc2018-07-16 19:05:05 +020066set(DOXYFILE_IN ${CMAKE_CURRENT_LIST_DIR}/zephyr.doxyfile.in)
67set(DOXYFILE_OUT ${CMAKE_CURRENT_BINARY_DIR}/zephyr.doxyfile)
Carles Cufi40b63e52019-02-19 13:47:03 +010068set(DOXY_OUT ${CMAKE_CURRENT_BINARY_DIR}/doxygen)
Carles Cufie182dbc2018-07-16 19:05:05 +020069set(RST_OUT ${CMAKE_CURRENT_BINARY_DIR}/rst)
70set(DOC_LOG ${CMAKE_CURRENT_BINARY_DIR}/doc.log)
71set(DOXY_LOG ${CMAKE_CURRENT_BINARY_DIR}/doxy.log)
72set(SPHINX_LOG ${CMAKE_CURRENT_BINARY_DIR}/sphinx.log)
73set(DOC_WARN ${CMAKE_CURRENT_BINARY_DIR}/doc.warnings)
Marti Bolivar0913c292018-10-09 12:42:03 -060074set(CONTENT_OUTPUTS ${CMAKE_CURRENT_BINARY_DIR}/extracted-content.txt)
Carles Cufiae699342018-07-09 14:12:17 +020075
Carles Cufie182dbc2018-07-16 19:05:05 +020076configure_file(${DOXYFILE_IN} ${DOXYFILE_OUT} @ONLY)
Anas Nashifb8fc4ec2019-02-08 21:45:41 -050077file(TOUCH ${CMAKE_CURRENT_BINARY_DIR}/Kconfig.modules)
Carles Cufiae699342018-07-09 14:12:17 +020078
Marc Herbertfc644812019-02-15 10:41:25 -080079# This command is used to copy all documentation source files from the
80# ZEPHYR_BASE/ environment variable into the build directory,
Marti Bolivard7dc1132018-10-16 08:39:35 -060081#
82# We need to make copies because Sphinx requires a single
83# documentation root directory, but Zephyr's documentation is
84# scattered around the tree in samples/, boards/, and doc/. Putting
85# them into a single rooted tree in the build directory is a
86# workaround for this limitation.
Marti Bolivar0913c292018-10-09 12:42:03 -060087set(EXTRACT_CONTENT_COMMAND
88 ${CMAKE_COMMAND} -E env
89 ${PYTHON_EXECUTABLE} scripts/extract_content.py
Marti Bolivar0913c292018-10-09 12:42:03 -060090 # Ignore any files in the output directory.
91 --ignore ${CMAKE_CURRENT_BINARY_DIR}
92 # Copy all files in doc to the rst folder.
93 "*:doc:${RST_OUT}"
Marti Bolivard7dc1132018-10-16 08:39:35 -060094 # We want to copy the .rst files in samples/ and boards/ to the rst
95 # folder, and also the doc folder inside rst.
Marti Bolivar0913c292018-10-09 12:42:03 -060096 #
97 # Some files refer to items in samples/ and boards/ relative to
98 # their actual position in the Zephyr tree. For example, in
99 # subsystems/sensor.rst:
100 #
101 # .. literalinclude:: ../../samples/sensor/mcp9808/src/main.c
102 #
Marti Bolivard7dc1132018-10-16 08:39:35 -0600103 # The additional copy is a hackaround so these references work.
Marti Bolivar0913c292018-10-09 12:42:03 -0600104 "*.rst:samples:${RST_OUT}" "*.rst:boards:${RST_OUT}"
105 "*.rst:samples:${RST_OUT}/doc" "*.rst:boards:${RST_OUT}/doc")
106
Carles Cufi15fbf702018-12-06 12:21:48 +0100107add_custom_target(
108 content
109 # Copy all files in doc/ to the rst folder
Marti Bolivar0913c292018-10-09 12:42:03 -0600110 COMMAND ${EXTRACT_CONTENT_COMMAND}
111 WORKING_DIRECTORY ${CMAKE_CURRENT_LIST_DIR}
Marc Herbertfc644812019-02-15 10:41:25 -0800112 COMMENT "Copying files to ${RST_OUT}"
Carles Cufi15fbf702018-12-06 12:21:48 +0100113)
Marti Bolivar0913c292018-10-09 12:42:03 -0600114
Carles Cufie182dbc2018-07-16 19:05:05 +0200115set(ARGS ${DOXYFILE_OUT})
Carles Cufiae699342018-07-09 14:12:17 +0200116
117add_custom_target(
118 doxy
119 COMMAND ${CMAKE_COMMAND}
120 -DCOMMAND=${DOXYGEN_EXECUTABLE}
121 -DARGS="${ARGS}"
122 -DOUTPUT_FILE=${DOXY_LOG}
123 -DERROR_FILE=${DOXY_LOG}
Carles Cufi2af9a9e2018-07-13 15:32:36 +0200124 -DWORKING_DIRECTORY=${CMAKE_CURRENT_LIST_DIR}
Carles Cufi45d58a72018-07-12 17:34:29 +0200125 -P ${ZEPHYR_BASE}/cmake/util/execute_process.cmake
Marc Herbertfc644812019-02-15 10:41:25 -0800126 COMMENT "Running ${DOXYGEN_EXECUTABLE}"
Carles Cufiae699342018-07-09 14:12:17 +0200127)
128
Marc Herbert52842312019-02-07 13:39:59 -0800129# Doxygen doesn't support incremental builds.
130# It could be ok because it's pretty fast.
131# But it's not because it has a cascade effect on sphinx:
132# https://sourceforge.net/p/doxygen/mailman/message/36580807/
133# For now this optimization speeds-up non-doxygen documentation work
134# only (by one order of magnitude).
135add_custom_target(
136 doxy_real_modified_times
137 COMMAND ${CMAKE_COMMAND} -E env
138 ${PYTHON_EXECUTABLE} scripts/restore_modification_times.py
Marc Herbertfc644812019-02-15 10:41:25 -0800139 --loglevel WARN ${DOXY_OUT}/xml
Marc Herbert52842312019-02-07 13:39:59 -0800140 WORKING_DIRECTORY ${CMAKE_CURRENT_LIST_DIR}
141)
142
143add_dependencies(doxy_real_modified_times doxy)
144
Carles Cufiae699342018-07-09 14:12:17 +0200145add_custom_target(
146 pristine
147 COMMAND ${CMAKE_COMMAND} -P ${ZEPHYR_BASE}/cmake/pristine.cmake
Carles Cufiae699342018-07-09 14:12:17 +0200148)
149
Carles Cufiae699342018-07-09 14:12:17 +0200150if(WIN32)
151 set(SEP ;)
152else()
153 set(SEP :)
154endif()
155
156add_custom_target(
157 kconfig
Carles Cufie182dbc2018-07-16 19:05:05 +0200158 COMMAND ${CMAKE_COMMAND} -E make_directory ${RST_OUT}/doc/reference/kconfig
159 COMMAND ${CMAKE_COMMAND} -E env
Carles Cufiae699342018-07-09 14:12:17 +0200160 PYTHONPATH="${ZEPHYR_BASE}/scripts/kconfig${SEP}$ENV{PYTHONPATH}"
161 srctree=${ZEPHYR_BASE}
Sebastian Bøe93230a52018-09-28 13:10:57 +0200162 KERNELVERSION=${KERNELVERSION}
Ulf Magnussond0e87522018-09-05 12:58:05 +0200163 BOARD_DIR=boards/*/*/
164 ARCH=*
Klaus Petersenc66cb762018-11-15 10:37:46 +0100165 ARCH_DIR=arch/
Anas Nashif96455d52018-09-04 14:34:06 -0500166 SOC_DIR=soc/
Carles Cufiae699342018-07-09 14:12:17 +0200167 SRCARCH=x86
Anas Nashifb8fc4ec2019-02-08 21:45:41 -0500168 PROJECT_BINARY_DIR=${CMAKE_CURRENT_BINARY_DIR}
Sebastian Bøe1ca10752019-02-12 12:05:36 +0100169 GENERATED_DTS_BOARD_CONF=not_applicable
Anas Nashif940a9312019-01-21 13:58:05 -0500170 KCONFIG_TURBO_MODE=${KCONFIG_TURBO_MODE}
Carles Cufifa26ef02019-01-30 17:54:21 +0100171 KCONFIG_DOC_MODE=1
Ulf Magnussona56be6f2018-08-17 22:27:01 +0200172 ${PYTHON_EXECUTABLE} scripts/genrest.py Kconfig ${RST_OUT}/doc/reference/kconfig/
Carles Cufi2af9a9e2018-07-13 15:32:36 +0200173 WORKING_DIRECTORY ${CMAKE_CURRENT_LIST_DIR}
Marc Herbertfc644812019-02-15 10:41:25 -0800174 COMMENT "Running genrest.py Kconfig ${RST_OUT}/doc/reference/kconfig/"
Carles Cufiae699342018-07-09 14:12:17 +0200175)
176
177set(KI_SCRIPT ${ZEPHYR_BASE}/scripts/filter-known-issues.py)
Daniel Leung9945e7f2018-08-23 11:11:11 -0700178set(FIX_TEX_SCRIPT ${ZEPHYR_BASE}/doc/scripts/fix_tex.py)
Carles Cufiae699342018-07-09 14:12:17 +0200179set(CONFIG_DIR ${ZEPHYR_BASE}/.known-issues/doc)
180
Daniel Leung9945e7f2018-08-23 11:11:11 -0700181#
182# HTML section
183#
Marti Bolivard9f512c2018-10-09 14:24:34 -0600184set(SPHINX_BUILD_HTML_COMMAND
185 ${CMAKE_COMMAND} -E env
186 ZEPHYR_BUILD=${CMAKE_CURRENT_BINARY_DIR}
187 ${SPHINXBUILD} -w ${SPHINX_LOG} -N -t ${DOC_TAG} -b html ${ALLSPHINXOPTS} ${RST_OUT}/doc ${SPHINX_OUTPUT_DIR_HTML})
188
189# The sphinx-html target is provided as a convenience for incremental
190# re-builds of content files without regenerating the entire docs
191# pipeline. It can be significantly faster than re-running the full
192# HTML build, but it has no idea if Doxygen, Kconfig, etc. need to be
193# regenerated. Use with caution.
194add_custom_target(
195 sphinx-html
196 COMMAND ${SPHINX_BUILD_HTML_COMMAND}
197 DEPENDS ${EXTRACT_CONTENT_OUTPUTS}
198 COMMENT "Just re-generating HTML (USE WITH CAUTION)"
199 USES_TERMINAL
200)
201
Marc Herbertfc644812019-02-15 10:41:25 -0800202# "breathe", the sphinx plugin that parses XML output from doxygen, has
203# an "everything on everything" dependency issue reported at:
204# https://github.com/michaeljones/breathe/issues/420 In other words
205# changing 1 source file costs the same build time than changing all
206# source files. breathe is fortunately smart enough not to run at all
207# when *nothing* has changed.
Carles Cufiae699342018-07-09 14:12:17 +0200208add_custom_target(
209 html
Marti Bolivard9f512c2018-10-09 14:24:34 -0600210 COMMAND ${SPHINX_BUILD_HTML_COMMAND}
Carles Cufiae699342018-07-09 14:12:17 +0200211 # Merge the Doxygen and Sphinx logs into a single file
212 COMMAND ${CMAKE_COMMAND} -P ${ZEPHYR_BASE}/cmake/util/fmerge.cmake ${DOC_LOG} ${DOXY_LOG} ${SPHINX_LOG}
213 COMMAND ${PYTHON_EXECUTABLE} ${KI_SCRIPT} --config-dir ${CONFIG_DIR} --errors ${DOC_WARN} --warnings ${DOC_WARN} ${DOC_LOG}
Carles Cufi2af9a9e2018-07-13 15:32:36 +0200214 WORKING_DIRECTORY ${CMAKE_CURRENT_LIST_DIR}
Marc Herbertfc644812019-02-15 10:41:25 -0800215 COMMENT "Generating HTML documentation with ${SPHINXBUILD} ${SPHINXOPTS}"
Carles Cufi60c55402018-07-15 18:57:01 +0200216 ${SPHINX_USES_TERMINAL}
Carles Cufiae699342018-07-09 14:12:17 +0200217)
Carles Cufi78964512018-07-15 18:49:37 +0200218
Daniel Leung9945e7f2018-08-23 11:11:11 -0700219#
220# LaTEX section
221#
Marti Bolivard9f512c2018-10-09 14:24:34 -0600222set(SPHINX_BUILD_LATEX_COMMAND
223 ${CMAKE_COMMAND} -E env
224 ZEPHYR_BUILD=${CMAKE_CURRENT_BINARY_DIR}
225 ${SPHINXBUILD} -w ${SPHINX_LOG} -N -t ${DOC_TAG} -b latex -t svgconvert ${ALLSPHINXOPTS} ${RST_OUT}/doc ${SPHINX_OUTPUT_DIR_LATEX})
226
227# The sphinx-latex target works similarly to sphinx-html, and carries
228# the same warnings.
229add_custom_target(
230 sphinx-latex
231 COMMAND ${SPHINX_BUILD_LATEX_COMMAND}
232 DEPENDS ${EXTRACT_CONTENT_OUTPUTS}
233 COMMENT "Just re-generating LaTeX (USE WITH CAUTION)"
234 USES_TERMINAL
235)
236
Daniel Leungc164c8e2018-09-10 17:29:20 -0700237add_custom_command(
238 OUTPUT ${SPHINX_OUTPUT_DIR_LATEX}/zephyr.tex
Marti Bolivard9f512c2018-10-09 14:24:34 -0600239 COMMAND ${SPHINX_BUILD_LATEX_COMMAND}
Daniel Leung9945e7f2018-08-23 11:11:11 -0700240 # Merge the Doxygen and Sphinx logs into a single file
241 COMMAND ${CMAKE_COMMAND} -P ${ZEPHYR_BASE}/cmake/util/fmerge.cmake ${DOC_LOG} ${DOXY_LOG} ${SPHINX_LOG}
242 COMMAND ${PYTHON_EXECUTABLE} ${KI_SCRIPT} --config-dir ${CONFIG_DIR} --errors ${DOC_WARN} --warnings ${DOC_WARN} ${DOC_LOG}
243 COMMAND ${PYTHON_EXECUTABLE} ${FIX_TEX_SCRIPT} ${SPHINX_OUTPUT_DIR_LATEX}/zephyr.tex
244 WORKING_DIRECTORY ${CMAKE_CURRENT_LIST_DIR}
Marti Bolivard9f512c2018-10-09 14:24:34 -0600245 COMMENT "Generating LaTeX documentation"
Carles Cufi7599fad2018-09-26 11:22:32 +0200246 ${SPHINX_USES_TERMINAL}
Daniel Leungc164c8e2018-09-10 17:29:20 -0700247)
248
249add_custom_target(
250 latex
251 DEPENDS ${SPHINX_OUTPUT_DIR_LATEX}/zephyr.tex
Daniel Leung9945e7f2018-08-23 11:11:11 -0700252)
253
254#
255# PDF section
256#
257if(NOT ${LATEXMK} STREQUAL LATEXMK-NOTFOUND)
258
259add_custom_command(
260 OUTPUT ${SPHINX_OUTPUT_DIR_LATEX}/zephyr.pdf
261 DEPENDS latexdocs ${SPHINX_OUTPUT_DIR_LATEX}/zephyr.tex
262 COMMAND ${CMAKE_COMMAND} -E env
Carles Cufi0698dba2018-10-02 10:30:39 +0200263 LATEXOPTS="-halt-on-error -no-shell-escape"
Daniel Leung9945e7f2018-08-23 11:11:11 -0700264 ${LATEXMK} -quiet -pdf -dvi- -ps-
265 WORKING_DIRECTORY ${SPHINX_OUTPUT_DIR_LATEX}
Marti Bolivard9f512c2018-10-09 14:24:34 -0600266 COMMENT "Generating PDF documentation"
Daniel Leung9945e7f2018-08-23 11:11:11 -0700267)
268
269if(NOT DEFINED SPHINX_OUTPUT_DIR)
270# Although latexmk allows specifying output directory,
271# makeindex fails if one is specified.
272# Hence the need of this to copy the PDF file over.
273add_custom_command(
274 OUTPUT ${SPHINX_OUTPUT_DIR_PDF}/zephyr.pdf
275 COMMAND ${CMAKE_COMMAND} -E make_directory ${SPHINX_OUTPUT_DIR_PDF}
276 COMMAND ${CMAKE_COMMAND} -E copy ${SPHINX_OUTPUT_DIR_LATEX}/zephyr.pdf ${SPHINX_OUTPUT_DIR_PDF}/zephyr.pdf
277 DEPENDS ${SPHINX_OUTPUT_DIR_LATEX}/zephyr.pdf
278)
279endif()
280
281add_custom_target(
282 pdf
283 DEPENDS ${SPHINX_OUTPUT_DIR_PDF}/zephyr.pdf
Daniel Leung9945e7f2018-08-23 11:11:11 -0700284)
285
286endif()
287
288#
289# Dependencies and final targets
290#
Marc Herbert52842312019-02-07 13:39:59 -0800291add_dependencies(html content doxy_real_modified_times kconfig)
Carles Cufi78964512018-07-15 18:49:37 +0200292
293add_custom_target(
294 htmldocs
295)
296add_dependencies(htmldocs html)
297
Marc Herbert52842312019-02-07 13:39:59 -0800298add_dependencies(latex content doxy_real_modified_times kconfig)
Daniel Leung9945e7f2018-08-23 11:11:11 -0700299
300add_custom_target(
301 latexdocs
302)
303add_dependencies(latexdocs latex)
304
305if(NOT ${LATEXMK} STREQUAL LATEXMK-NOTFOUND)
306
307add_custom_target(
308 pdfdocs
Daniel Leungc164c8e2018-09-10 17:29:20 -0700309 DEPENDS latexdocs pdf
Daniel Leung9945e7f2018-08-23 11:11:11 -0700310)
311add_dependencies(pdfdocs pdf)
312
313endif()