1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
|
include(FindPackageHandleStandardArgs)
macro(_Sphinx_find_executable _exe)
string(TOUPPER "${_exe}" _uc)
# sphinx-(build|quickstart)-3 x.x.x
# FIXME: This works on Fedora (and probably most other UNIX like targets).
# Windows targets and PIP installs might need some work.
find_program(
SPHINX_${_uc}_EXECUTABLE
NAMES "sphinx-${_exe}-3" "sphinx-${_exe}" "sphinx-${_exe}.exe")
if(SPHINX_${_uc}_EXECUTABLE)
execute_process(
COMMAND "${SPHINX_${_uc}_EXECUTABLE}" --version
RESULT_VARIABLE _result
OUTPUT_VARIABLE _output
OUTPUT_STRIP_TRAILING_WHITESPACE)
if(_result EQUAL 0 AND _output MATCHES " v?([0-9]+\\.[0-9]+\\.[0-9]+)$")
set(SPHINX_${_uc}_VERSION "${CMAKE_MATCH_1}")
endif()
if(NOT TARGET Sphinx::${_exe})
add_executable(Sphinx::${_exe} IMPORTED GLOBAL)
set_target_properties(Sphinx::${_exe} PROPERTIES
IMPORTED_LOCATION "${SPHINX_${_uc}_EXECUTABLE}")
endif()
set(Sphinx_${_exe}_FOUND TRUE)
else()
set(Sphinx_${_exe}_FOUND FALSE)
endif()
unset(_uc)
endmacro()
macro(_Sphinx_find_module _name _module)
string(TOUPPER "${_name}" _Sphinx_uc)
if(SPHINX_PYTHON_EXECUTABLE)
execute_process(
COMMAND ${SPHINX_PYTHON_EXECUTABLE} -m ${_module} --version
RESULT_VARIABLE _result
OUTPUT_VARIABLE _output
OUTPUT_STRIP_TRAILING_WHITESPACE
ERROR_QUIET)
if(_result EQUAL 0)
if(_output MATCHES " v?([0-9]+\\.[0-9]+\\.[0-9]+)$")
set(SPHINX_${_Sphinx_uc}_VERSION "${CMAKE_MATCH_1}")
endif()
if(NOT TARGET Sphinx::${_name})
set(SPHINX_${_Sphinx_uc}_EXECUTABLE "${SPHINX_PYTHON_EXECUTABLE} -m ${_module}")
add_executable(Sphinx::${_name} IMPORTED GLOBAL)
set_target_properties(Sphinx::${_name} PROPERTIES
IMPORTED_LOCATION "${SPHINX_PYTHON_EXECUTABLE}")
endif()
set(Sphinx_${_name}_ARGS -m ${_module})
set(Sphinx_${_name}_FOUND TRUE)
else()
set(Sphinx_${_name}_FOUND FALSE)
endif()
else()
set(Sphinx_${_name}_FOUND FALSE)
endif()
unset(_Sphinx_uc)
endmacro()
macro(_Sphinx_find_extension _ext)
if(SPHINX_PYTHON_EXECUTABLE)
execute_process(
COMMAND ${SPHINX_PYTHON_EXECUTABLE} -c "import ${_ext}"
RESULT_VARIABLE _result)
if(_result EQUAL 0)
set(Sphinx_${_ext}_FOUND TRUE)
else()
set(Sphinx_${_ext}_FOUND FALSE)
endif()
endif()
endmacro()
#
# Find sphinx-build and sphinx-quickstart.
#
# Find sphinx-build shim.
_Sphinx_find_executable(build)
if(SPHINX_BUILD_EXECUTABLE)
# Find sphinx-quickstart shim.
_Sphinx_find_executable(quickstart)
# Locate Python executable
if(CMAKE_HOST_WIN32)
# script-build on Windows located under (when PIP is used):
# C:/Program Files/PythonXX/Scripts
# C:/Users/username/AppData/Roaming/Python/PythonXX/Sripts
#
# Python modules are installed under:
# C:/Program Files/PythonXX/Lib
# C:/Users/username/AppData/Roaming/Python/PythonXX/site-packages
#
# To verify a given module is installed, use the Python base directory
# and test if either Lib/module.py or site-packages/module.py exists.
get_filename_component(_Sphinx_directory "${SPHINX_BUILD_EXECUTABLE}" DIRECTORY)
get_filename_component(_Sphinx_directory "${_Sphinx_directory}" DIRECTORY)
if(EXISTS "${_Sphinx_directory}/python.exe")
set(SPHINX_PYTHON_EXECUTABLE "${_Sphinx_directory}/python.exe")
endif()
unset(_Sphinx_directory)
else()
file(READ "${SPHINX_BUILD_EXECUTABLE}" _Sphinx_script)
if(_Sphinx_script MATCHES "^#!([^\n]+)")
string(STRIP "${CMAKE_MATCH_1}" _Sphinx_shebang)
if(EXISTS "${_Sphinx_shebang}")
set(SPHINX_PYTHON_EXECUTABLE "${_Sphinx_shebang}")
endif()
endif()
unset(_Sphinx_script)
unset(_Sphinx_shebang)
endif()
endif()
if(NOT SPHINX_PYTHON_EXECUTABLE)
# Python executable cannot be extracted from shim shebang or path if e.g.
# virtual environments are used, fallback to find package. Assume the
# correct installation is found, the setup is probably broken in more ways
# than one otherwise.
find_package(Python3 QUIET COMPONENTS Interpreter)
if(TARGET Python3::Interpreter)
set(SPHINX_PYTHON_EXECUTABLE ${Python3_EXECUTABLE})
# Revert to "python -m sphinx" if shim cannot be found.
if(NOT SPHINX_BUILD_EXECUTABLE)
_Sphinx_find_module(build sphinx)
_Sphinx_find_module(quickstart sphinx.cmd.quickstart)
endif()
endif()
endif()
#
# Verify components are available.
#
if(SPHINX_BUILD_VERSION)
foreach(_Sphinx_component IN LISTS Sphinx_FIND_COMPONENTS)
if(_Sphinx_component STREQUAL "build")
# Do nothing, sphinx-build is always required.
continue()
elseif(_Sphinx_component STREQUAL "quickstart")
# Do nothing, sphinx-quickstart is optional, but looked up by default.
continue()
endif()
_Sphinx_find_extension(${_Sphinx_component})
endforeach()
unset(_Sphinx_component)
#
# Verify both executables are part of the Sphinx distribution.
#
if(SPHINX_QUICKSTART_VERSION AND NOT SPHINX_BUILD_VERSION STREQUAL SPHINX_QUICKSTART_VERSION)
message(FATAL_ERROR "Versions for sphinx-build (${SPHINX_BUILD_VERSION}) "
"and sphinx-quickstart (${SPHINX_QUICKSTART_VERSION}) "
"do not match")
endif()
endif()
find_package_handle_standard_args(
Sphinx
VERSION_VAR SPHINX_BUILD_VERSION
REQUIRED_VARS SPHINX_BUILD_EXECUTABLE SPHINX_BUILD_VERSION
HANDLE_COMPONENTS)
# Generate a conf.py template file using sphinx-quickstart.
#
# sphinx-quickstart allows for quiet operation and a lot of settings can be
# specified as command line arguments, therefore its not required to parse the
# generated conf.py.
function(_Sphinx_generate_confpy _target _cachedir)
if(NOT TARGET Sphinx::quickstart)
message(FATAL_ERROR "sphinx-quickstart is not available, needed by"
"sphinx_add_docs for target ${_target}")
endif()
if(NOT DEFINED SPHINX_PROJECT)
set(SPHINX_PROJECT ${PROJECT_NAME})
endif()
if(NOT DEFINED SPHINX_AUTHOR)
set(SPHINX_AUTHOR "${SPHINX_PROJECT} committers")
endif()
if(NOT DEFINED SPHINX_COPYRIGHT)
string(TIMESTAMP "%Y, ${SPHINX_AUTHOR}" SPHINX_COPYRIGHT)
endif()
if(NOT DEFINED SPHINX_VERSION)
set(SPHINX_VERSION "${PROJECT_VERSION_MAJOR}.${PROJECT_VERSION_MINOR}.${PROJECT_VERSION_PATCH}")
endif()
if(NOT DEFINED SPHINX_RELEASE)
set(SPHINX_RELEASE "${PROJECT_VERSION}")
endif()
if(NOT DEFINED SPHINX_LANGUAGE)
set(SPHINX_LANGUAGE "en")
endif()
if(NOT DEFINED SPHINX_MASTER)
set(SPHINX_MASTER "index")
endif()
set(_known_exts autodoc doctest intersphinx todo coverage imgmath mathjax
ifconfig viewcode githubpages)
# Standard extensions can be added using --ext-<name> option,
# non-standard extensions will be added using --extensions=<names, ...> option.
if(DEFINED SPHINX_EXTENSIONS)
foreach(_ext ${SPHINX_EXTENSIONS})
set(_is_known_ext FALSE)
foreach(_known_ext ${_known_exsts})
if(_ext STREQUAL _known_ext)
set(_opts "${opts} --ext-${_ext}")
set(_is_known_ext TRUE)
break()
endif()
endforeach()
if(NOT _is_known_ext)
if(_exts)
set(_exts "${_exts},${_ext}")
else()
set(_exts "${_ext}")
endif()
endif()
endforeach()
endif()
if(_exts)
set(_exts "--extensions=${_exts}")
endif()
# Use sphinx-quick-start tp generate the conf.py
set(_templatedir "${CMAKE_CURRENT_BINARY_DIR}/${_target}.template")
file(MAKE_DIRECTORY "${_templatedir}")
string(REPLACE " " ";" _Sphinx_executable ${SPHINX_QUICKSTART_EXECUTABLE})
execute_process(
COMMAND ${_Sphinx_executable}
-q --no-makefile --no-batchfile
-p "${SPHINX_PROJECT}"
-a "${SPHINX_AUTHOR}"
-v "${SPHINX_VERSION}"
-r "${SPHINX_RELEASE}"
-l "${SPHINX_LANGUAGE}"
--master "${SPHINX_MASTER}"
${_opts} ${_exts} "${_templatedir}"
RESULT_VARIABLE _result
OUTPUT_QUIET)
unset(_Sphinx_executable)
if(_result EQUAL 0 AND EXISTS "${_templatedir}/conf.py")
# We have to prepend the following python code in order to be able
# to import non-standard extensions
file(READ "${_templatedir}/conf.py" _template_conf_file)
file(WRITE "${_cachedir}/conf.py" "import os, sys\nsys.path.insert(0, os.path.abspath('.'))\n\n")
file(APPEND "${_cachedir}/conf.py" ${_template_conf_file})
unset(_template_conf_file)
endif()
file(REMOVE_RECURSE "${_templatedir}")
if(NOT _result EQUAL 0 OR NOT EXISTS "${_cachedir}/conf.py")
message(FATAL_ERROR "Sphinx configuration file not generated for "
"target ${_target}")
endif()
endfunction()
function(sphinx_add_docs _target)
set(_opts)
set(_single_opts BUILDER OUTPUT_DIRECTORY SOURCE_DIRECTORY)
set(_multi_opts EXTENSION_FILES)
cmake_parse_arguments(_args "${_opts}" "${_single_opts}" "${_multi_opts}" ${ARGN})
if(NOT _args_BUILDER)
message(FATAL_ERROR "Sphinx builder not specified for target ${_target}")
elseif(NOT _args_SOURCE_DIRECTORY)
message(FATAL_ERROR "Sphinx source directory not specified for target ${_target}")
else()
if(NOT IS_ABSOLUTE "${_args_SOURCE_DIRECTORY}")
get_filename_component(_sourcedir "${_args_SOURCE_DIRECTORY}" ABSOLUTE)
else()
set(_sourcedir "${_args_SOURCE_DIRECTORY}")
endif()
if(NOT IS_DIRECTORY "${_sourcedir}")
message(FATAL_ERROR "Sphinx source directory '${_sourcedir}' for"
"target ${_target} does not exist")
endif()
endif()
set(_builder "${_args_BUILDER}")
if(_args_OUTPUT_DIRECTORY)
set(_outputdir "${_args_OUTPUT_DIRECTORY}")
else()
set(_outputdir "${CMAKE_CURRENT_BINARY_DIR}/${_target}")
endif()
set(_cachedir "${CMAKE_CURRENT_BINARY_DIR}/${_target}.cache")
file(MAKE_DIRECTORY "${_cachedir}")
file(MAKE_DIRECTORY "${_cachedir}/_static")
# Make copy of extension files to cache directory
if(_args_EXTENSION_FILES)
foreach(_extension_file ${_args_EXTENSION_FILES})
if(NOT IS_ABSOLUTE "${_extension_file}")
get_filename_component(_srcfilepath "${_extension_file}" ABSOLUTE)
else()
set(_srcfilepath "${_extension_file}")
endif()
file(COPY "${_srcfilepath}" DESTINATION "${_cachedir}")
endforeach()
endif(_args_EXTENSION_FILES)
# FIXME: This step must become optional! Based on existance of conf.py in
# the source directory and whether or not sphinx-quickstart was
# found. If both are missing, it's an error!
_Sphinx_generate_confpy(${_target} "${_cachedir}")
string(REPLACE " " ";" _Sphinx_executable ${SPHINX_BUILD_EXECUTABLE})
add_custom_target(
${_target} ALL
COMMAND ${_Sphinx_executable}
-b ${_builder}
-d "${CMAKE_CURRENT_BINARY_DIR}/${_target}.cache/_doctrees"
-c "${CMAKE_CURRENT_BINARY_DIR}/${_target}.cache"
"${_sourcedir}"
"${_outputdir}"
DEPENDS ${_depends})
unset(_Sphinx_executable)
endfunction()
|
