Anas Nashif | 3ae5262 | 2019-04-06 09:08:09 -0400 | [diff] [blame] | 1 | # SPDX-License-Identifier: Apache-2.0 |
| 2 | |
Anas Nashif | 5060ca6 | 2018-12-11 10:33:23 -0500 | [diff] [blame] | 3 | cmake_minimum_required(VERSION 3.13.1) |
Sebastian Bøe | 5748fe1 | 2019-01-04 09:13:07 +0100 | [diff] [blame] | 4 | project(Zephyr-Kernel-Doc LANGUAGES) |
Carles Cufi | ae69934 | 2018-07-09 14:12:17 +0200 | [diff] [blame] | 5 | |
Carles Cufi | 1aa4d8d | 2019-03-28 17:49:25 +0100 | [diff] [blame] | 6 | # Find west to (optionally) process modules for Kconfig |
| 7 | find_program( |
| 8 | WEST |
| 9 | west |
| 10 | ) |
| 11 | if(${WEST} STREQUAL WEST-NOTFOUND) |
| 12 | unset(WEST) |
| 13 | endif() |
| 14 | |
Carles Cufi | b73790b | 2019-05-23 16:35:20 +0200 | [diff] [blame] | 15 | file(TO_CMAKE_PATH "$ENV{ZEPHYR_BASE}" ZEPHYR_BASE) |
Carles Cufi | ae69934 | 2018-07-09 14:12:17 +0200 | [diff] [blame] | 16 | |
| 17 | message(STATUS "Zephyr base: ${ZEPHYR_BASE}") |
Marti Bolivar | 2b3d9df | 2019-07-22 11:00:59 -0600 | [diff] [blame] | 18 | if(DEFINED WEST) |
| 19 | message(STATUS "West: ${WEST}") |
| 20 | else() |
| 21 | message(STATUS "West: not found") |
| 22 | endif() |
Carles Cufi | ae69934 | 2018-07-09 14:12:17 +0200 | [diff] [blame] | 23 | |
| 24 | find_package(PythonInterp 3.4) |
| 25 | set(DOXYGEN_SKIP_DOT True) |
| 26 | find_package(Doxygen REQUIRED) |
Carles Cufi | 0698dba | 2018-10-02 10:30:39 +0200 | [diff] [blame] | 27 | find_package(LATEX) |
Carles Cufi | ae69934 | 2018-07-09 14:12:17 +0200 | [diff] [blame] | 28 | |
| 29 | find_program( |
| 30 | SPHINXBUILD |
Marc Herbert | a49f9eb | 2019-02-04 15:24:01 -0800 | [diff] [blame] | 31 | NAMES sphinx-build-3 sphinx-build |
Carles Cufi | ae69934 | 2018-07-09 14:12:17 +0200 | [diff] [blame] | 32 | ) |
| 33 | if(${SPHINXBUILD} STREQUAL SPHINXBUILD-NOTFOUND) |
| 34 | message(FATAL_ERROR "The 'sphinx-build' command was not found. Make sure you have Sphinx installed.") |
| 35 | endif() |
| 36 | |
Carles Cufi | f5f1b22 | 2019-05-23 16:37:58 +0200 | [diff] [blame] | 37 | # Include version info |
| 38 | include(${ZEPHYR_BASE}/cmake/version.cmake) |
| 39 | # Process modules |
| 40 | include(${ZEPHYR_BASE}/cmake/zephyr_module.cmake) |
| 41 | |
Daniel Leung | 9945e7f | 2018-08-23 11:11:11 -0700 | [diff] [blame] | 42 | # Note that this won't force fatal error if latexmk is not found. |
| 43 | # Not having LaTeX tools should not prevent people from generating HTML docs. |
| 44 | find_program( |
| 45 | LATEXMK |
| 46 | latexmk |
| 47 | ) |
| 48 | if(${LATEXMK} STREQUAL LATEXMK-NOTFOUND) |
| 49 | message(WARNING "The 'latexmk' command was not found. Targets to build PDF will not be available.") |
| 50 | endif() |
| 51 | |
Carles Cufi | ae69934 | 2018-07-09 14:12:17 +0200 | [diff] [blame] | 52 | if(NOT DEFINED SPHINXOPTS) |
| 53 | set(SPHINXOPTS -q) |
Carles Cufi | d505ca7 | 2018-07-13 12:37:13 +0200 | [diff] [blame] | 54 | else() |
| 55 | separate_arguments(SPHINXOPTS) |
Carles Cufi | ae69934 | 2018-07-09 14:12:17 +0200 | [diff] [blame] | 56 | endif() |
| 57 | |
Carles Cufi | 896a696 | 2018-08-16 13:45:59 +0200 | [diff] [blame] | 58 | if(NOT DEFINED SPHINX_OUTPUT_DIR) |
Daniel Leung | 9945e7f | 2018-08-23 11:11:11 -0700 | [diff] [blame] | 59 | set(SPHINX_OUTPUT_DIR_HTML ${CMAKE_CURRENT_BINARY_DIR}/html) |
| 60 | set(SPHINX_OUTPUT_DIR_LATEX ${CMAKE_CURRENT_BINARY_DIR}/latex) |
| 61 | set(SPHINX_OUTPUT_DIR_PDF ${CMAKE_CURRENT_BINARY_DIR}/pdf) |
| 62 | else() |
Marti Bolivar | 2952bf8 | 2018-10-09 13:28:41 -0600 | [diff] [blame] | 63 | # SPHINX_OUTPUT_DIR is used to specify exactly where HTML (or other |
| 64 | # outputs) are placed, so no /html, /latex, /pdf suffixes are needed. |
Daniel Leung | 9945e7f | 2018-08-23 11:11:11 -0700 | [diff] [blame] | 65 | set(SPHINX_OUTPUT_DIR_HTML ${SPHINX_OUTPUT_DIR}) |
| 66 | set(SPHINX_OUTPUT_DIR_LATEX ${SPHINX_OUTPUT_DIR}) |
| 67 | set(SPHINX_OUTPUT_DIR_PDF ${SPHINX_OUTPUT_DIR}) |
Carles Cufi | 896a696 | 2018-08-16 13:45:59 +0200 | [diff] [blame] | 68 | endif() |
| 69 | |
Carles Cufi | ae69934 | 2018-07-09 14:12:17 +0200 | [diff] [blame] | 70 | if(NOT DEFINED DOC_TAG) |
| 71 | set(DOC_TAG development) |
| 72 | endif() |
| 73 | |
| 74 | # Internal variables. |
Carles Cufi | 2af9a9e | 2018-07-13 15:32:36 +0200 | [diff] [blame] | 75 | set(ALLSPHINXOPTS -d ${CMAKE_CURRENT_BINARY_DIR}/doctrees ${SPHINXOPTS}) |
Carles Cufi | 60c5540 | 2018-07-15 18:57:01 +0200 | [diff] [blame] | 76 | if("-q" IN_LIST ALLSPHINXOPTS) |
| 77 | set(SPHINX_USES_TERMINAL ) |
| 78 | else() |
| 79 | set(SPHINX_USES_TERMINAL USES_TERMINAL) |
| 80 | endif() |
| 81 | |
Carles Cufi | ae69934 | 2018-07-09 14:12:17 +0200 | [diff] [blame] | 82 | # the i18n builder cannot share the environment and doctrees with the others |
Carles Cufi | d505ca7 | 2018-07-13 12:37:13 +0200 | [diff] [blame] | 83 | set(I18NSPHINXOPTS ${SPHINXOPTS}) |
Carles Cufi | ae69934 | 2018-07-09 14:12:17 +0200 | [diff] [blame] | 84 | |
Carles Cufi | e182dbc | 2018-07-16 19:05:05 +0200 | [diff] [blame] | 85 | set(DOXYFILE_IN ${CMAKE_CURRENT_LIST_DIR}/zephyr.doxyfile.in) |
| 86 | set(DOXYFILE_OUT ${CMAKE_CURRENT_BINARY_DIR}/zephyr.doxyfile) |
Carles Cufi | 40b63e5 | 2019-02-19 13:47:03 +0100 | [diff] [blame] | 87 | set(DOXY_OUT ${CMAKE_CURRENT_BINARY_DIR}/doxygen) |
Carles Cufi | e182dbc | 2018-07-16 19:05:05 +0200 | [diff] [blame] | 88 | set(RST_OUT ${CMAKE_CURRENT_BINARY_DIR}/rst) |
| 89 | set(DOC_LOG ${CMAKE_CURRENT_BINARY_DIR}/doc.log) |
| 90 | set(DOXY_LOG ${CMAKE_CURRENT_BINARY_DIR}/doxy.log) |
| 91 | set(SPHINX_LOG ${CMAKE_CURRENT_BINARY_DIR}/sphinx.log) |
| 92 | set(DOC_WARN ${CMAKE_CURRENT_BINARY_DIR}/doc.warnings) |
Marti Bolivar | 0913c29 | 2018-10-09 12:42:03 -0600 | [diff] [blame] | 93 | set(CONTENT_OUTPUTS ${CMAKE_CURRENT_BINARY_DIR}/extracted-content.txt) |
Carles Cufi | ae69934 | 2018-07-09 14:12:17 +0200 | [diff] [blame] | 94 | |
Carles Cufi | e182dbc | 2018-07-16 19:05:05 +0200 | [diff] [blame] | 95 | configure_file(${DOXYFILE_IN} ${DOXYFILE_OUT} @ONLY) |
Carles Cufi | ae69934 | 2018-07-09 14:12:17 +0200 | [diff] [blame] | 96 | |
Marc Herbert | fc64481 | 2019-02-15 10:41:25 -0800 | [diff] [blame] | 97 | # This command is used to copy all documentation source files from the |
| 98 | # ZEPHYR_BASE/ environment variable into the build directory, |
Marti Bolivar | d7dc113 | 2018-10-16 08:39:35 -0600 | [diff] [blame] | 99 | # |
| 100 | # We need to make copies because Sphinx requires a single |
| 101 | # documentation root directory, but Zephyr's documentation is |
| 102 | # scattered around the tree in samples/, boards/, and doc/. Putting |
| 103 | # them into a single rooted tree in the build directory is a |
| 104 | # workaround for this limitation. |
Marti Bolivar | 0913c29 | 2018-10-09 12:42:03 -0600 | [diff] [blame] | 105 | set(EXTRACT_CONTENT_COMMAND |
| 106 | ${CMAKE_COMMAND} -E env |
Marti Bolivar | f3d1386 | 2019-05-10 04:23:23 -0600 | [diff] [blame] | 107 | ZEPHYR_BASE=${ZEPHYR_BASE} |
Marti Bolivar | 0913c29 | 2018-10-09 12:42:03 -0600 | [diff] [blame] | 108 | ${PYTHON_EXECUTABLE} scripts/extract_content.py |
Marti Bolivar | 0913c29 | 2018-10-09 12:42:03 -0600 | [diff] [blame] | 109 | # Ignore any files in the output directory. |
| 110 | --ignore ${CMAKE_CURRENT_BINARY_DIR} |
| 111 | # Copy all files in doc to the rst folder. |
| 112 | "*:doc:${RST_OUT}" |
Marti Bolivar | d7dc113 | 2018-10-16 08:39:35 -0600 | [diff] [blame] | 113 | # We want to copy the .rst files in samples/ and boards/ to the rst |
| 114 | # folder, and also the doc folder inside rst. |
Marti Bolivar | 0913c29 | 2018-10-09 12:42:03 -0600 | [diff] [blame] | 115 | # |
| 116 | # Some files refer to items in samples/ and boards/ relative to |
| 117 | # their actual position in the Zephyr tree. For example, in |
| 118 | # subsystems/sensor.rst: |
| 119 | # |
| 120 | # .. literalinclude:: ../../samples/sensor/mcp9808/src/main.c |
| 121 | # |
Marti Bolivar | d7dc113 | 2018-10-16 08:39:35 -0600 | [diff] [blame] | 122 | # The additional copy is a hackaround so these references work. |
Marti Bolivar | 0913c29 | 2018-10-09 12:42:03 -0600 | [diff] [blame] | 123 | "*.rst:samples:${RST_OUT}" "*.rst:boards:${RST_OUT}" |
| 124 | "*.rst:samples:${RST_OUT}/doc" "*.rst:boards:${RST_OUT}/doc") |
| 125 | |
Carles Cufi | 15fbf70 | 2018-12-06 12:21:48 +0100 | [diff] [blame] | 126 | add_custom_target( |
| 127 | content |
| 128 | # Copy all files in doc/ to the rst folder |
Marti Bolivar | 0913c29 | 2018-10-09 12:42:03 -0600 | [diff] [blame] | 129 | COMMAND ${EXTRACT_CONTENT_COMMAND} |
| 130 | WORKING_DIRECTORY ${CMAKE_CURRENT_LIST_DIR} |
Marc Herbert | fc64481 | 2019-02-15 10:41:25 -0800 | [diff] [blame] | 131 | COMMENT "Copying files to ${RST_OUT}" |
Carles Cufi | 15fbf70 | 2018-12-06 12:21:48 +0100 | [diff] [blame] | 132 | ) |
Marti Bolivar | 0913c29 | 2018-10-09 12:42:03 -0600 | [diff] [blame] | 133 | |
Marc Herbert | 2270f4b | 2019-02-15 11:49:49 -0800 | [diff] [blame] | 134 | # For incremental builds not to miss any source change this MUST be kept |
| 135 | # a superset of INPUT= and FILE_PATTERNS= in zephyr.doxyfile.in |
| 136 | file(GLOB_RECURSE DOXY_SOURCES |
| 137 | ${ZEPHYR_BASE}/include/*.[c,h,S] |
| 138 | ${ZEPHYR_BASE}/lib/libc/*.[c,h,S] |
David B. Kinder | b30b52a | 2019-06-25 15:54:19 -0700 | [diff] [blame] | 139 | ${ZEPHYR_BASE}/subsys/testsuite/ztest/include/*.[h,c,S] |
Marc Herbert | 2270f4b | 2019-02-15 11:49:49 -0800 | [diff] [blame] | 140 | ${ZEPHYR_BASE}/tests/*.[h,c,S] |
| 141 | ) |
| 142 | # For debug. Also find generated list in doc/_build/(build.ninja|CMakeFiles/) |
| 143 | # message("DOXY_SOURCES= " ${DOXY_SOURCES}) |
Carles Cufi | ae69934 | 2018-07-09 14:12:17 +0200 | [diff] [blame] | 144 | |
Marc Herbert | 2270f4b | 2019-02-15 11:49:49 -0800 | [diff] [blame] | 145 | set(ARGS ${DOXYFILE_OUT}) |
| 146 | set(DOXY_RUN_TSTAMP ${CMAKE_CURRENT_BINARY_DIR}/last_doxy_run_tstamp) |
| 147 | |
| 148 | |
| 149 | # Create timestamp first so we re-run if source files are edited while |
| 150 | # doxygen is running |
| 151 | add_custom_command( |
| 152 | OUTPUT ${DOXY_RUN_TSTAMP} |
| 153 | COMMAND cmake -E touch ${DOXY_RUN_TSTAMP} |
Carles Cufi | ae69934 | 2018-07-09 14:12:17 +0200 | [diff] [blame] | 154 | COMMAND ${CMAKE_COMMAND} |
| 155 | -DCOMMAND=${DOXYGEN_EXECUTABLE} |
| 156 | -DARGS="${ARGS}" |
| 157 | -DOUTPUT_FILE=${DOXY_LOG} |
| 158 | -DERROR_FILE=${DOXY_LOG} |
Carles Cufi | 2af9a9e | 2018-07-13 15:32:36 +0200 | [diff] [blame] | 159 | -DWORKING_DIRECTORY=${CMAKE_CURRENT_LIST_DIR} |
Carles Cufi | 45d58a7 | 2018-07-12 17:34:29 +0200 | [diff] [blame] | 160 | -P ${ZEPHYR_BASE}/cmake/util/execute_process.cmake |
Marc Herbert | 2270f4b | 2019-02-15 11:49:49 -0800 | [diff] [blame] | 161 | DEPENDS ${DOXY_SOURCES} |
Marc Herbert | fc64481 | 2019-02-15 10:41:25 -0800 | [diff] [blame] | 162 | COMMENT "Running ${DOXYGEN_EXECUTABLE}" |
Carles Cufi | ae69934 | 2018-07-09 14:12:17 +0200 | [diff] [blame] | 163 | ) |
| 164 | |
Marc Herbert | 5284231 | 2019-02-07 13:39:59 -0800 | [diff] [blame] | 165 | # Doxygen doesn't support incremental builds. |
| 166 | # It could be ok because it's pretty fast. |
| 167 | # But it's not because it has a cascade effect on sphinx: |
| 168 | # https://sourceforge.net/p/doxygen/mailman/message/36580807/ |
| 169 | # For now this optimization speeds-up non-doxygen documentation work |
| 170 | # only (by one order of magnitude). |
| 171 | add_custom_target( |
| 172 | doxy_real_modified_times |
| 173 | COMMAND ${CMAKE_COMMAND} -E env |
| 174 | ${PYTHON_EXECUTABLE} scripts/restore_modification_times.py |
Marc Herbert | fc64481 | 2019-02-15 10:41:25 -0800 | [diff] [blame] | 175 | --loglevel WARN ${DOXY_OUT}/xml |
Marc Herbert | 5284231 | 2019-02-07 13:39:59 -0800 | [diff] [blame] | 176 | WORKING_DIRECTORY ${CMAKE_CURRENT_LIST_DIR} |
Marc Herbert | 2270f4b | 2019-02-15 11:49:49 -0800 | [diff] [blame] | 177 | DEPENDS ${DOXY_RUN_TSTAMP} |
| 178 | COMMENT "Fixing modification times of ${DOXY_OUT}/xml/ output" |
Marc Herbert | 5284231 | 2019-02-07 13:39:59 -0800 | [diff] [blame] | 179 | ) |
| 180 | |
Carles Cufi | ae69934 | 2018-07-09 14:12:17 +0200 | [diff] [blame] | 181 | add_custom_target( |
| 182 | pristine |
| 183 | COMMAND ${CMAKE_COMMAND} -P ${ZEPHYR_BASE}/cmake/pristine.cmake |
Carles Cufi | ae69934 | 2018-07-09 14:12:17 +0200 | [diff] [blame] | 184 | ) |
| 185 | |
Carles Cufi | ae69934 | 2018-07-09 14:12:17 +0200 | [diff] [blame] | 186 | if(WIN32) |
Carles Cufi | 8645cc2 | 2019-09-06 15:56:21 +0200 | [diff] [blame^] | 187 | set(SEP $<SEMICOLON>) |
Carles Cufi | ae69934 | 2018-07-09 14:12:17 +0200 | [diff] [blame] | 188 | else() |
| 189 | set(SEP :) |
| 190 | endif() |
| 191 | |
| 192 | add_custom_target( |
| 193 | kconfig |
Carles Cufi | e182dbc | 2018-07-16 19:05:05 +0200 | [diff] [blame] | 194 | COMMAND ${CMAKE_COMMAND} -E make_directory ${RST_OUT}/doc/reference/kconfig |
| 195 | COMMAND ${CMAKE_COMMAND} -E env |
Carles Cufi | ae69934 | 2018-07-09 14:12:17 +0200 | [diff] [blame] | 196 | PYTHONPATH="${ZEPHYR_BASE}/scripts/kconfig${SEP}$ENV{PYTHONPATH}" |
Marti Bolivar | f3d1386 | 2019-05-10 04:23:23 -0600 | [diff] [blame] | 197 | ZEPHYR_BASE=${ZEPHYR_BASE} |
Carles Cufi | ae69934 | 2018-07-09 14:12:17 +0200 | [diff] [blame] | 198 | srctree=${ZEPHYR_BASE} |
Sebastian Bøe | 93230a5 | 2018-09-28 13:10:57 +0200 | [diff] [blame] | 199 | KERNELVERSION=${KERNELVERSION} |
Ulf Magnusson | d0e8752 | 2018-09-05 12:58:05 +0200 | [diff] [blame] | 200 | BOARD_DIR=boards/*/*/ |
| 201 | ARCH=* |
Klaus Petersen | c66cb76 | 2018-11-15 10:37:46 +0100 | [diff] [blame] | 202 | ARCH_DIR=arch/ |
Anas Nashif | 96455d5 | 2018-09-04 14:34:06 -0500 | [diff] [blame] | 203 | SOC_DIR=soc/ |
Carles Cufi | ae69934 | 2018-07-09 14:12:17 +0200 | [diff] [blame] | 204 | SRCARCH=x86 |
Sebastian Bøe | 7061c03 | 2019-03-01 12:57:11 +0100 | [diff] [blame] | 205 | CMAKE_BINARY_DIR=${CMAKE_BINARY_DIR} |
Carles Cufi | c6249ac | 2019-03-28 17:51:39 +0100 | [diff] [blame] | 206 | KCONFIG_WARN_UNDEF=y |
Anas Nashif | 940a931 | 2019-01-21 13:58:05 -0500 | [diff] [blame] | 207 | KCONFIG_TURBO_MODE=${KCONFIG_TURBO_MODE} |
Carles Cufi | fa26ef0 | 2019-01-30 17:54:21 +0100 | [diff] [blame] | 208 | KCONFIG_DOC_MODE=1 |
Ulf Magnusson | a56be6f | 2018-08-17 22:27:01 +0200 | [diff] [blame] | 209 | ${PYTHON_EXECUTABLE} scripts/genrest.py Kconfig ${RST_OUT}/doc/reference/kconfig/ |
Carles Cufi | 2af9a9e | 2018-07-13 15:32:36 +0200 | [diff] [blame] | 210 | WORKING_DIRECTORY ${CMAKE_CURRENT_LIST_DIR} |
Marc Herbert | fc64481 | 2019-02-15 10:41:25 -0800 | [diff] [blame] | 211 | COMMENT "Running genrest.py Kconfig ${RST_OUT}/doc/reference/kconfig/" |
Carles Cufi | ae69934 | 2018-07-09 14:12:17 +0200 | [diff] [blame] | 212 | ) |
| 213 | |
| 214 | set(KI_SCRIPT ${ZEPHYR_BASE}/scripts/filter-known-issues.py) |
Daniel Leung | 9945e7f | 2018-08-23 11:11:11 -0700 | [diff] [blame] | 215 | set(FIX_TEX_SCRIPT ${ZEPHYR_BASE}/doc/scripts/fix_tex.py) |
Ulf Magnusson | 259c240 | 2019-03-05 01:54:15 +0100 | [diff] [blame] | 216 | set(CONF_DIR ${ZEPHYR_BASE}/.known-issues/doc) |
Carles Cufi | ae69934 | 2018-07-09 14:12:17 +0200 | [diff] [blame] | 217 | |
Daniel Leung | 9945e7f | 2018-08-23 11:11:11 -0700 | [diff] [blame] | 218 | # |
| 219 | # HTML section |
| 220 | # |
Marti Bolivar | d9f512c | 2018-10-09 14:24:34 -0600 | [diff] [blame] | 221 | set(SPHINX_BUILD_HTML_COMMAND |
| 222 | ${CMAKE_COMMAND} -E env |
Marti Bolivar | f3d1386 | 2019-05-10 04:23:23 -0600 | [diff] [blame] | 223 | ZEPHYR_BASE=${ZEPHYR_BASE} |
Marti Bolivar | d9f512c | 2018-10-09 14:24:34 -0600 | [diff] [blame] | 224 | ZEPHYR_BUILD=${CMAKE_CURRENT_BINARY_DIR} |
| 225 | ${SPHINXBUILD} -w ${SPHINX_LOG} -N -t ${DOC_TAG} -b html ${ALLSPHINXOPTS} ${RST_OUT}/doc ${SPHINX_OUTPUT_DIR_HTML}) |
| 226 | |
| 227 | # The sphinx-html target is provided as a convenience for incremental |
| 228 | # re-builds of content files without regenerating the entire docs |
| 229 | # pipeline. It can be significantly faster than re-running the full |
| 230 | # HTML build, but it has no idea if Doxygen, Kconfig, etc. need to be |
| 231 | # regenerated. Use with caution. |
| 232 | add_custom_target( |
| 233 | sphinx-html |
| 234 | COMMAND ${SPHINX_BUILD_HTML_COMMAND} |
| 235 | DEPENDS ${EXTRACT_CONTENT_OUTPUTS} |
| 236 | COMMENT "Just re-generating HTML (USE WITH CAUTION)" |
| 237 | USES_TERMINAL |
| 238 | ) |
| 239 | |
Marc Herbert | fc64481 | 2019-02-15 10:41:25 -0800 | [diff] [blame] | 240 | # "breathe", the sphinx plugin that parses XML output from doxygen, has |
| 241 | # an "everything on everything" dependency issue reported at: |
| 242 | # https://github.com/michaeljones/breathe/issues/420 In other words |
| 243 | # changing 1 source file costs the same build time than changing all |
| 244 | # source files. breathe is fortunately smart enough not to run at all |
| 245 | # when *nothing* has changed. |
Carles Cufi | ae69934 | 2018-07-09 14:12:17 +0200 | [diff] [blame] | 246 | add_custom_target( |
| 247 | html |
Marti Bolivar | d9f512c | 2018-10-09 14:24:34 -0600 | [diff] [blame] | 248 | COMMAND ${SPHINX_BUILD_HTML_COMMAND} |
Carles Cufi | ae69934 | 2018-07-09 14:12:17 +0200 | [diff] [blame] | 249 | # Merge the Doxygen and Sphinx logs into a single file |
| 250 | COMMAND ${CMAKE_COMMAND} -P ${ZEPHYR_BASE}/cmake/util/fmerge.cmake ${DOC_LOG} ${DOXY_LOG} ${SPHINX_LOG} |
Ulf Magnusson | 259c240 | 2019-03-05 01:54:15 +0100 | [diff] [blame] | 251 | COMMAND ${PYTHON_EXECUTABLE} ${KI_SCRIPT} --config-dir ${CONF_DIR} --errors ${DOC_WARN} --warnings ${DOC_WARN} ${DOC_LOG} |
Carles Cufi | 2af9a9e | 2018-07-13 15:32:36 +0200 | [diff] [blame] | 252 | WORKING_DIRECTORY ${CMAKE_CURRENT_LIST_DIR} |
Marc Herbert | fc64481 | 2019-02-15 10:41:25 -0800 | [diff] [blame] | 253 | COMMENT "Generating HTML documentation with ${SPHINXBUILD} ${SPHINXOPTS}" |
Carles Cufi | 60c5540 | 2018-07-15 18:57:01 +0200 | [diff] [blame] | 254 | ${SPHINX_USES_TERMINAL} |
Carles Cufi | ae69934 | 2018-07-09 14:12:17 +0200 | [diff] [blame] | 255 | ) |
Carles Cufi | 7896451 | 2018-07-15 18:49:37 +0200 | [diff] [blame] | 256 | |
Daniel Leung | 9945e7f | 2018-08-23 11:11:11 -0700 | [diff] [blame] | 257 | # |
| 258 | # LaTEX section |
| 259 | # |
Marti Bolivar | d9f512c | 2018-10-09 14:24:34 -0600 | [diff] [blame] | 260 | set(SPHINX_BUILD_LATEX_COMMAND |
| 261 | ${CMAKE_COMMAND} -E env |
| 262 | ZEPHYR_BUILD=${CMAKE_CURRENT_BINARY_DIR} |
| 263 | ${SPHINXBUILD} -w ${SPHINX_LOG} -N -t ${DOC_TAG} -b latex -t svgconvert ${ALLSPHINXOPTS} ${RST_OUT}/doc ${SPHINX_OUTPUT_DIR_LATEX}) |
| 264 | |
| 265 | # The sphinx-latex target works similarly to sphinx-html, and carries |
| 266 | # the same warnings. |
| 267 | add_custom_target( |
| 268 | sphinx-latex |
| 269 | COMMAND ${SPHINX_BUILD_LATEX_COMMAND} |
| 270 | DEPENDS ${EXTRACT_CONTENT_OUTPUTS} |
| 271 | COMMENT "Just re-generating LaTeX (USE WITH CAUTION)" |
| 272 | USES_TERMINAL |
| 273 | ) |
| 274 | |
Daniel Leung | c164c8e | 2018-09-10 17:29:20 -0700 | [diff] [blame] | 275 | add_custom_command( |
| 276 | OUTPUT ${SPHINX_OUTPUT_DIR_LATEX}/zephyr.tex |
Marti Bolivar | d9f512c | 2018-10-09 14:24:34 -0600 | [diff] [blame] | 277 | COMMAND ${SPHINX_BUILD_LATEX_COMMAND} |
Daniel Leung | 9945e7f | 2018-08-23 11:11:11 -0700 | [diff] [blame] | 278 | # Merge the Doxygen and Sphinx logs into a single file |
| 279 | COMMAND ${CMAKE_COMMAND} -P ${ZEPHYR_BASE}/cmake/util/fmerge.cmake ${DOC_LOG} ${DOXY_LOG} ${SPHINX_LOG} |
Ulf Magnusson | 259c240 | 2019-03-05 01:54:15 +0100 | [diff] [blame] | 280 | COMMAND ${PYTHON_EXECUTABLE} ${KI_SCRIPT} --config-dir ${CONF_DIR} --errors ${DOC_WARN} --warnings ${DOC_WARN} ${DOC_LOG} |
Daniel Leung | 9945e7f | 2018-08-23 11:11:11 -0700 | [diff] [blame] | 281 | COMMAND ${PYTHON_EXECUTABLE} ${FIX_TEX_SCRIPT} ${SPHINX_OUTPUT_DIR_LATEX}/zephyr.tex |
| 282 | WORKING_DIRECTORY ${CMAKE_CURRENT_LIST_DIR} |
Marti Bolivar | d9f512c | 2018-10-09 14:24:34 -0600 | [diff] [blame] | 283 | COMMENT "Generating LaTeX documentation" |
Carles Cufi | 7599fad | 2018-09-26 11:22:32 +0200 | [diff] [blame] | 284 | ${SPHINX_USES_TERMINAL} |
Daniel Leung | c164c8e | 2018-09-10 17:29:20 -0700 | [diff] [blame] | 285 | ) |
| 286 | |
| 287 | add_custom_target( |
| 288 | latex |
| 289 | DEPENDS ${SPHINX_OUTPUT_DIR_LATEX}/zephyr.tex |
Daniel Leung | 9945e7f | 2018-08-23 11:11:11 -0700 | [diff] [blame] | 290 | ) |
| 291 | |
| 292 | # |
| 293 | # PDF section |
| 294 | # |
| 295 | if(NOT ${LATEXMK} STREQUAL LATEXMK-NOTFOUND) |
| 296 | |
| 297 | add_custom_command( |
| 298 | OUTPUT ${SPHINX_OUTPUT_DIR_LATEX}/zephyr.pdf |
| 299 | DEPENDS latexdocs ${SPHINX_OUTPUT_DIR_LATEX}/zephyr.tex |
| 300 | COMMAND ${CMAKE_COMMAND} -E env |
Carles Cufi | 0698dba | 2018-10-02 10:30:39 +0200 | [diff] [blame] | 301 | LATEXOPTS="-halt-on-error -no-shell-escape" |
Daniel Leung | 9945e7f | 2018-08-23 11:11:11 -0700 | [diff] [blame] | 302 | ${LATEXMK} -quiet -pdf -dvi- -ps- |
| 303 | WORKING_DIRECTORY ${SPHINX_OUTPUT_DIR_LATEX} |
Marti Bolivar | d9f512c | 2018-10-09 14:24:34 -0600 | [diff] [blame] | 304 | COMMENT "Generating PDF documentation" |
Daniel Leung | 9945e7f | 2018-08-23 11:11:11 -0700 | [diff] [blame] | 305 | ) |
| 306 | |
| 307 | if(NOT DEFINED SPHINX_OUTPUT_DIR) |
| 308 | # Although latexmk allows specifying output directory, |
| 309 | # makeindex fails if one is specified. |
| 310 | # Hence the need of this to copy the PDF file over. |
| 311 | add_custom_command( |
| 312 | OUTPUT ${SPHINX_OUTPUT_DIR_PDF}/zephyr.pdf |
| 313 | COMMAND ${CMAKE_COMMAND} -E make_directory ${SPHINX_OUTPUT_DIR_PDF} |
| 314 | COMMAND ${CMAKE_COMMAND} -E copy ${SPHINX_OUTPUT_DIR_LATEX}/zephyr.pdf ${SPHINX_OUTPUT_DIR_PDF}/zephyr.pdf |
| 315 | DEPENDS ${SPHINX_OUTPUT_DIR_LATEX}/zephyr.pdf |
| 316 | ) |
| 317 | endif() |
| 318 | |
| 319 | add_custom_target( |
| 320 | pdf |
| 321 | DEPENDS ${SPHINX_OUTPUT_DIR_PDF}/zephyr.pdf |
Daniel Leung | 9945e7f | 2018-08-23 11:11:11 -0700 | [diff] [blame] | 322 | ) |
| 323 | |
| 324 | endif() |
| 325 | |
| 326 | # |
| 327 | # Dependencies and final targets |
| 328 | # |
Marc Herbert | 5284231 | 2019-02-07 13:39:59 -0800 | [diff] [blame] | 329 | add_dependencies(html content doxy_real_modified_times kconfig) |
Carles Cufi | 7896451 | 2018-07-15 18:49:37 +0200 | [diff] [blame] | 330 | |
| 331 | add_custom_target( |
| 332 | htmldocs |
| 333 | ) |
| 334 | add_dependencies(htmldocs html) |
| 335 | |
Marc Herbert | 5284231 | 2019-02-07 13:39:59 -0800 | [diff] [blame] | 336 | add_dependencies(latex content doxy_real_modified_times kconfig) |
Daniel Leung | 9945e7f | 2018-08-23 11:11:11 -0700 | [diff] [blame] | 337 | |
| 338 | add_custom_target( |
| 339 | latexdocs |
| 340 | ) |
| 341 | add_dependencies(latexdocs latex) |
| 342 | |
| 343 | if(NOT ${LATEXMK} STREQUAL LATEXMK-NOTFOUND) |
| 344 | |
| 345 | add_custom_target( |
| 346 | pdfdocs |
Daniel Leung | c164c8e | 2018-09-10 17:29:20 -0700 | [diff] [blame] | 347 | DEPENDS latexdocs pdf |
Daniel Leung | 9945e7f | 2018-08-23 11:11:11 -0700 | [diff] [blame] | 348 | ) |
| 349 | add_dependencies(pdfdocs pdf) |
| 350 | |
| 351 | endif() |