blob: 1254b0c4542a4dd0fb3f55dd3028b0e904ae3640 [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)
68set(RST_OUT ${CMAKE_CURRENT_BINARY_DIR}/rst)
69set(DOC_LOG ${CMAKE_CURRENT_BINARY_DIR}/doc.log)
70set(DOXY_LOG ${CMAKE_CURRENT_BINARY_DIR}/doxy.log)
71set(SPHINX_LOG ${CMAKE_CURRENT_BINARY_DIR}/sphinx.log)
72set(DOC_WARN ${CMAKE_CURRENT_BINARY_DIR}/doc.warnings)
Marti Bolivar0913c292018-10-09 12:42:03 -060073set(CONTENT_OUTPUTS ${CMAKE_CURRENT_BINARY_DIR}/extracted-content.txt)
Carles Cufiae699342018-07-09 14:12:17 +020074
Carles Cufie182dbc2018-07-16 19:05:05 +020075configure_file(${DOXYFILE_IN} ${DOXYFILE_OUT} @ONLY)
Anas Nashifb8fc4ec2019-02-08 21:45:41 -050076file(TOUCH ${CMAKE_CURRENT_BINARY_DIR}/Kconfig.modules)
Carles Cufiae699342018-07-09 14:12:17 +020077
Carles Cufi15fbf702018-12-06 12:21:48 +010078# This command is used to copy all documentation source files into the build
79# directory,
Marti Bolivard7dc1132018-10-16 08:39:35 -060080#
81# We need to make copies because Sphinx requires a single
82# documentation root directory, but Zephyr's documentation is
83# scattered around the tree in samples/, boards/, and doc/. Putting
84# them into a single rooted tree in the build directory is a
85# workaround for this limitation.
Marti Bolivar0913c292018-10-09 12:42:03 -060086set(EXTRACT_CONTENT_COMMAND
87 ${CMAKE_COMMAND} -E env
88 ${PYTHON_EXECUTABLE} scripts/extract_content.py
Marti Bolivar0913c292018-10-09 12:42:03 -060089 # Ignore any files in the output directory.
90 --ignore ${CMAKE_CURRENT_BINARY_DIR}
91 # Copy all files in doc to the rst folder.
92 "*:doc:${RST_OUT}"
Marti Bolivard7dc1132018-10-16 08:39:35 -060093 # We want to copy the .rst files in samples/ and boards/ to the rst
94 # folder, and also the doc folder inside rst.
Marti Bolivar0913c292018-10-09 12:42:03 -060095 #
96 # Some files refer to items in samples/ and boards/ relative to
97 # their actual position in the Zephyr tree. For example, in
98 # subsystems/sensor.rst:
99 #
100 # .. literalinclude:: ../../samples/sensor/mcp9808/src/main.c
101 #
Marti Bolivard7dc1132018-10-16 08:39:35 -0600102 # The additional copy is a hackaround so these references work.
Marti Bolivar0913c292018-10-09 12:42:03 -0600103 "*.rst:samples:${RST_OUT}" "*.rst:boards:${RST_OUT}"
104 "*.rst:samples:${RST_OUT}/doc" "*.rst:boards:${RST_OUT}/doc")
105
Carles Cufi15fbf702018-12-06 12:21:48 +0100106add_custom_target(
107 content
108 # Copy all files in doc/ to the rst folder
Marti Bolivar0913c292018-10-09 12:42:03 -0600109 COMMAND ${EXTRACT_CONTENT_COMMAND}
110 WORKING_DIRECTORY ${CMAKE_CURRENT_LIST_DIR}
Carles Cufi15fbf702018-12-06 12:21:48 +0100111)
Marti Bolivar0913c292018-10-09 12:42:03 -0600112
Carles Cufie182dbc2018-07-16 19:05:05 +0200113set(ARGS ${DOXYFILE_OUT})
Carles Cufiae699342018-07-09 14:12:17 +0200114
115add_custom_target(
116 doxy
117 COMMAND ${CMAKE_COMMAND}
118 -DCOMMAND=${DOXYGEN_EXECUTABLE}
119 -DARGS="${ARGS}"
120 -DOUTPUT_FILE=${DOXY_LOG}
121 -DERROR_FILE=${DOXY_LOG}
Carles Cufi2af9a9e2018-07-13 15:32:36 +0200122 -DWORKING_DIRECTORY=${CMAKE_CURRENT_LIST_DIR}
Carles Cufi45d58a72018-07-12 17:34:29 +0200123 -P ${ZEPHYR_BASE}/cmake/util/execute_process.cmake
Carles Cufiae699342018-07-09 14:12:17 +0200124)
125
126add_custom_target(
127 pristine
128 COMMAND ${CMAKE_COMMAND} -P ${ZEPHYR_BASE}/cmake/pristine.cmake
Carles Cufiae699342018-07-09 14:12:17 +0200129)
130
Carles Cufiae699342018-07-09 14:12:17 +0200131if(WIN32)
132 set(SEP ;)
133else()
134 set(SEP :)
135endif()
136
137add_custom_target(
138 kconfig
Carles Cufie182dbc2018-07-16 19:05:05 +0200139 COMMAND ${CMAKE_COMMAND} -E make_directory ${RST_OUT}/doc/reference/kconfig
140 COMMAND ${CMAKE_COMMAND} -E env
Carles Cufiae699342018-07-09 14:12:17 +0200141 PYTHONPATH="${ZEPHYR_BASE}/scripts/kconfig${SEP}$ENV{PYTHONPATH}"
142 srctree=${ZEPHYR_BASE}
Sebastian Bøe93230a52018-09-28 13:10:57 +0200143 KERNELVERSION=${KERNELVERSION}
Ulf Magnussond0e87522018-09-05 12:58:05 +0200144 BOARD_DIR=boards/*/*/
145 ARCH=*
Klaus Petersenc66cb762018-11-15 10:37:46 +0100146 ARCH_DIR=arch/
Anas Nashif96455d52018-09-04 14:34:06 -0500147 SOC_DIR=soc/
Carles Cufiae699342018-07-09 14:12:17 +0200148 SRCARCH=x86
Anas Nashifb8fc4ec2019-02-08 21:45:41 -0500149 PROJECT_BINARY_DIR=${CMAKE_CURRENT_BINARY_DIR}
Sebastian Bøe1ca10752019-02-12 12:05:36 +0100150 GENERATED_DTS_BOARD_CONF=not_applicable
Anas Nashif940a9312019-01-21 13:58:05 -0500151 KCONFIG_TURBO_MODE=${KCONFIG_TURBO_MODE}
Carles Cufifa26ef02019-01-30 17:54:21 +0100152 KCONFIG_DOC_MODE=1
Ulf Magnussona56be6f2018-08-17 22:27:01 +0200153 ${PYTHON_EXECUTABLE} scripts/genrest.py Kconfig ${RST_OUT}/doc/reference/kconfig/
Carles Cufi2af9a9e2018-07-13 15:32:36 +0200154 WORKING_DIRECTORY ${CMAKE_CURRENT_LIST_DIR}
Carles Cufiae699342018-07-09 14:12:17 +0200155)
156
157set(KI_SCRIPT ${ZEPHYR_BASE}/scripts/filter-known-issues.py)
Daniel Leung9945e7f2018-08-23 11:11:11 -0700158set(FIX_TEX_SCRIPT ${ZEPHYR_BASE}/doc/scripts/fix_tex.py)
Carles Cufiae699342018-07-09 14:12:17 +0200159set(CONFIG_DIR ${ZEPHYR_BASE}/.known-issues/doc)
160
Daniel Leung9945e7f2018-08-23 11:11:11 -0700161#
162# HTML section
163#
Marti Bolivard9f512c2018-10-09 14:24:34 -0600164set(SPHINX_BUILD_HTML_COMMAND
165 ${CMAKE_COMMAND} -E env
166 ZEPHYR_BUILD=${CMAKE_CURRENT_BINARY_DIR}
167 ${SPHINXBUILD} -w ${SPHINX_LOG} -N -t ${DOC_TAG} -b html ${ALLSPHINXOPTS} ${RST_OUT}/doc ${SPHINX_OUTPUT_DIR_HTML})
168
169# The sphinx-html target is provided as a convenience for incremental
170# re-builds of content files without regenerating the entire docs
171# pipeline. It can be significantly faster than re-running the full
172# HTML build, but it has no idea if Doxygen, Kconfig, etc. need to be
173# regenerated. Use with caution.
174add_custom_target(
175 sphinx-html
176 COMMAND ${SPHINX_BUILD_HTML_COMMAND}
177 DEPENDS ${EXTRACT_CONTENT_OUTPUTS}
178 COMMENT "Just re-generating HTML (USE WITH CAUTION)"
179 USES_TERMINAL
180)
181
Carles Cufiae699342018-07-09 14:12:17 +0200182add_custom_target(
183 html
Marti Bolivard9f512c2018-10-09 14:24:34 -0600184 COMMAND ${SPHINX_BUILD_HTML_COMMAND}
Carles Cufiae699342018-07-09 14:12:17 +0200185 # Merge the Doxygen and Sphinx logs into a single file
186 COMMAND ${CMAKE_COMMAND} -P ${ZEPHYR_BASE}/cmake/util/fmerge.cmake ${DOC_LOG} ${DOXY_LOG} ${SPHINX_LOG}
187 COMMAND ${PYTHON_EXECUTABLE} ${KI_SCRIPT} --config-dir ${CONFIG_DIR} --errors ${DOC_WARN} --warnings ${DOC_WARN} ${DOC_LOG}
Carles Cufi2af9a9e2018-07-13 15:32:36 +0200188 WORKING_DIRECTORY ${CMAKE_CURRENT_LIST_DIR}
Marti Bolivard9f512c2018-10-09 14:24:34 -0600189 COMMENT "Generating HTML documentation"
Carles Cufi60c55402018-07-15 18:57:01 +0200190 ${SPHINX_USES_TERMINAL}
Carles Cufiae699342018-07-09 14:12:17 +0200191)
Carles Cufi78964512018-07-15 18:49:37 +0200192
Daniel Leung9945e7f2018-08-23 11:11:11 -0700193#
194# LaTEX section
195#
Marti Bolivard9f512c2018-10-09 14:24:34 -0600196set(SPHINX_BUILD_LATEX_COMMAND
197 ${CMAKE_COMMAND} -E env
198 ZEPHYR_BUILD=${CMAKE_CURRENT_BINARY_DIR}
199 ${SPHINXBUILD} -w ${SPHINX_LOG} -N -t ${DOC_TAG} -b latex -t svgconvert ${ALLSPHINXOPTS} ${RST_OUT}/doc ${SPHINX_OUTPUT_DIR_LATEX})
200
201# The sphinx-latex target works similarly to sphinx-html, and carries
202# the same warnings.
203add_custom_target(
204 sphinx-latex
205 COMMAND ${SPHINX_BUILD_LATEX_COMMAND}
206 DEPENDS ${EXTRACT_CONTENT_OUTPUTS}
207 COMMENT "Just re-generating LaTeX (USE WITH CAUTION)"
208 USES_TERMINAL
209)
210
Daniel Leungc164c8e2018-09-10 17:29:20 -0700211add_custom_command(
212 OUTPUT ${SPHINX_OUTPUT_DIR_LATEX}/zephyr.tex
Marti Bolivard9f512c2018-10-09 14:24:34 -0600213 COMMAND ${SPHINX_BUILD_LATEX_COMMAND}
Daniel Leung9945e7f2018-08-23 11:11:11 -0700214 # Merge the Doxygen and Sphinx logs into a single file
215 COMMAND ${CMAKE_COMMAND} -P ${ZEPHYR_BASE}/cmake/util/fmerge.cmake ${DOC_LOG} ${DOXY_LOG} ${SPHINX_LOG}
216 COMMAND ${PYTHON_EXECUTABLE} ${KI_SCRIPT} --config-dir ${CONFIG_DIR} --errors ${DOC_WARN} --warnings ${DOC_WARN} ${DOC_LOG}
217 COMMAND ${PYTHON_EXECUTABLE} ${FIX_TEX_SCRIPT} ${SPHINX_OUTPUT_DIR_LATEX}/zephyr.tex
218 WORKING_DIRECTORY ${CMAKE_CURRENT_LIST_DIR}
Marti Bolivard9f512c2018-10-09 14:24:34 -0600219 COMMENT "Generating LaTeX documentation"
Carles Cufi7599fad2018-09-26 11:22:32 +0200220 ${SPHINX_USES_TERMINAL}
Daniel Leungc164c8e2018-09-10 17:29:20 -0700221)
222
223add_custom_target(
224 latex
225 DEPENDS ${SPHINX_OUTPUT_DIR_LATEX}/zephyr.tex
Daniel Leung9945e7f2018-08-23 11:11:11 -0700226)
227
228#
229# PDF section
230#
231if(NOT ${LATEXMK} STREQUAL LATEXMK-NOTFOUND)
232
233add_custom_command(
234 OUTPUT ${SPHINX_OUTPUT_DIR_LATEX}/zephyr.pdf
235 DEPENDS latexdocs ${SPHINX_OUTPUT_DIR_LATEX}/zephyr.tex
236 COMMAND ${CMAKE_COMMAND} -E env
Carles Cufi0698dba2018-10-02 10:30:39 +0200237 LATEXOPTS="-halt-on-error -no-shell-escape"
Daniel Leung9945e7f2018-08-23 11:11:11 -0700238 ${LATEXMK} -quiet -pdf -dvi- -ps-
239 WORKING_DIRECTORY ${SPHINX_OUTPUT_DIR_LATEX}
Marti Bolivard9f512c2018-10-09 14:24:34 -0600240 COMMENT "Generating PDF documentation"
Daniel Leung9945e7f2018-08-23 11:11:11 -0700241)
242
243if(NOT DEFINED SPHINX_OUTPUT_DIR)
244# Although latexmk allows specifying output directory,
245# makeindex fails if one is specified.
246# Hence the need of this to copy the PDF file over.
247add_custom_command(
248 OUTPUT ${SPHINX_OUTPUT_DIR_PDF}/zephyr.pdf
249 COMMAND ${CMAKE_COMMAND} -E make_directory ${SPHINX_OUTPUT_DIR_PDF}
250 COMMAND ${CMAKE_COMMAND} -E copy ${SPHINX_OUTPUT_DIR_LATEX}/zephyr.pdf ${SPHINX_OUTPUT_DIR_PDF}/zephyr.pdf
251 DEPENDS ${SPHINX_OUTPUT_DIR_LATEX}/zephyr.pdf
252)
253endif()
254
255add_custom_target(
256 pdf
257 DEPENDS ${SPHINX_OUTPUT_DIR_PDF}/zephyr.pdf
Daniel Leung9945e7f2018-08-23 11:11:11 -0700258)
259
260endif()
261
262#
263# Dependencies and final targets
264#
Carles Cufi78964512018-07-15 18:49:37 +0200265add_dependencies(html content doxy kconfig)
266
267add_custom_target(
268 htmldocs
269)
270add_dependencies(htmldocs html)
271
Daniel Leung9945e7f2018-08-23 11:11:11 -0700272add_dependencies(latex content doxy kconfig)
273
274add_custom_target(
275 latexdocs
276)
277add_dependencies(latexdocs latex)
278
279if(NOT ${LATEXMK} STREQUAL LATEXMK-NOTFOUND)
280
281add_custom_target(
282 pdfdocs
Daniel Leungc164c8e2018-09-10 17:29:20 -0700283 DEPENDS latexdocs pdf
Daniel Leung9945e7f2018-08-23 11:11:11 -0700284)
285add_dependencies(pdfdocs pdf)
286
287endif()