| 1 |
# Generate documentation in HTML and PDF format using Sphinx. |
| 2 |
|
| 3 |
set(GENERATE_DOC TRUE) |
| 4 |
|
| 5 |
# We use the Sphinx documentation generator to render HTML and manual |
| 6 |
# pages from the user and reference documentation in ReST format. |
| 7 |
find_package(Sphinx QUIET) |
| 8 |
if(NOT SPHINX_FOUND) |
| 9 |
message(WARNING "Unable to find Sphinx documentation generator") |
| 10 |
set(GENERATE_DOC FALSE) |
| 11 |
endif(NOT SPHINX_FOUND) |
| 12 |
|
| 13 |
if(SPHINX_MAJOR_VERSION LESS 1) |
| 14 |
message(WARNING "Sphinx is older than v1.0, not building docs") |
| 15 |
set(GENERATE_DOC FALSE) |
| 16 |
endif(SPHINX_MAJOR_VERSION LESS 1) |
| 17 |
|
| 18 |
if(GENERATE_DOC) |
| 19 |
# documentation tools |
| 20 |
set(SOURCE_BUILD_DIR "${CMAKE_CURRENT_SOURCE_DIR}/_build") |
| 21 |
# configured documentation tools and intermediate build results |
| 22 |
set(BINARY_BUILD_DIR "${CMAKE_CURRENT_BINARY_DIR}/_build") |
| 23 |
# static ReST documentation sources |
| 24 |
set(SOURCES_DIR "${CMAKE_CURRENT_BINARY_DIR}/_sources") |
| 25 |
# generated ReST documentation sources |
| 26 |
set(REF_SOURCES_DIR "${SOURCES_DIR}/reference") |
| 27 |
# master document with modules index |
| 28 |
set(REF_MASTER_DOC "modules") |
| 29 |
|
| 30 |
# substitute variables in configuration and scripts |
| 31 |
foreach(file |
| 32 |
conf.py |
| 33 |
sources.cmake |
| 34 |
) |
| 35 |
configure_file( |
| 36 |
"${SOURCE_BUILD_DIR}/${file}.in" |
| 37 |
"${BINARY_BUILD_DIR}/${file}" |
| 38 |
@ONLY |
| 39 |
) |
| 40 |
endforeach(file) |
| 41 |
|
| 42 |
set(CLEAN_FILES |
| 43 |
"${BINARY_BUILD_DIR}/html" |
| 44 |
) |
| 45 |
|
| 46 |
add_custom_target(ALL |
| 47 |
DEPENDS "${REF_SOURCES_DIR}/${REF_MASTER_DOC}.rst" |
| 48 |
) |
| 49 |
|
| 50 |
# Sphinx requires all sources in the same directory tree. As we wish |
| 51 |
# to include generated reference documention from the build tree, we |
| 52 |
# copy static ReST documents to the build tree before calling Sphinx. |
| 53 |
add_custom_target(doc_sources ALL |
| 54 |
"${CMAKE_COMMAND}" -P "${BINARY_BUILD_DIR}/sources.cmake" |
| 55 |
) |
| 56 |
list(APPEND CLEAN_FILES |
| 57 |
"${SOURCES_DIR}" |
| 58 |
) |
| 59 |
|
| 60 |
# note the trailing slash to exclude directory name |
| 61 |
install(DIRECTORY "${SOURCES_DIR}/" |
| 62 |
DESTINATION "share/doc/mydumper" |
| 63 |
) |
| 64 |
|
| 65 |
# Sphinx cache with pickled ReST documents |
| 66 |
set(SPHINX_CACHE_DIR "${CMAKE_CURRENT_BINARY_DIR}/_doctrees") |
| 67 |
# HTML output directory |
| 68 |
set(SPHINX_HTML_DIR "${CMAKE_CURRENT_BINARY_DIR}/html") |
| 69 |
|
| 70 |
# This target builds HTML documentation using Sphinx. |
| 71 |
add_custom_target(doc_html ALL |
| 72 |
${SPHINX_EXECUTABLE} |
| 73 |
-q -b html |
| 74 |
-c "${BINARY_BUILD_DIR}" |
| 75 |
-d "${SPHINX_CACHE_DIR}" |
| 76 |
"${SOURCES_DIR}" |
| 77 |
"${SPHINX_HTML_DIR}" |
| 78 |
COMMENT "Building HTML documentation with Sphinx" |
| 79 |
) |
| 80 |
list(APPEND CLEAN_FILES |
| 81 |
"${SPHINX_CACHE_DIR}" |
| 82 |
"${SPHINX_HTML_DIR}" |
| 83 |
) |
| 84 |
add_dependencies(doc_html |
| 85 |
doc_sources |
| 86 |
) |
| 87 |
install(DIRECTORY "${SPHINX_HTML_DIR}" |
| 88 |
DESTINATION "share/doc/mydumper" |
| 89 |
) |
| 90 |
|
| 91 |
# HTML output directory |
| 92 |
set(SPHINX_MAN_DIR "${CMAKE_CURRENT_BINARY_DIR}/man") |
| 93 |
# This target builds a manual page using Sphinx. |
| 94 |
|
| 95 |
add_custom_target(doc_man ALL |
| 96 |
${SPHINX_EXECUTABLE} |
| 97 |
-q -b man |
| 98 |
-c "${BINARY_BUILD_DIR}" |
| 99 |
-d "${SPHINX_CACHE_DIR}" |
| 100 |
"${SOURCES_DIR}" |
| 101 |
"${SPHINX_MAN_DIR}" |
| 102 |
COMMENT "Building manual page with Sphinx" |
| 103 |
) |
| 104 |
list(APPEND CLEAN_FILES |
| 105 |
"${SPHINX_MAN_DIR}" |
| 106 |
) |
| 107 |
add_dependencies(doc_man |
| 108 |
doc_sources |
| 109 |
) |
| 110 |
# serialize Sphinx targets to avoid cache conflicts in parallel builds |
| 111 |
add_dependencies(doc_man |
| 112 |
doc_html |
| 113 |
) |
| 114 |
install(FILES "${SPHINX_MAN_DIR}/mydumper.1" "${SPHINX_MAN_DIR}/myloader.1" |
| 115 |
DESTINATION "share/man/man1" |
| 116 |
) |
| 117 |
|
| 118 |
# This target builds PDF documentation using Sphinx and LaTeX. |
| 119 |
if(PDFLATEX_COMPILER) |
| 120 |
# PDF output directory |
| 121 |
set(SPHINX_PDF_DIR "${CMAKE_CURRENT_BINARY_DIR}/pdf") |
| 122 |
|
| 123 |
add_custom_target(doc_pdf ALL |
| 124 |
${SPHINX_EXECUTABLE} |
| 125 |
-q -b latex |
| 126 |
-c "${BINARY_BUILD_DIR}" |
| 127 |
-d "${SPHINX_CACHE_DIR}" |
| 128 |
"${SOURCES_DIR}" |
| 129 |
"${SPHINX_PDF_DIR}" |
| 130 |
COMMENT "Building PDF documentation with Sphinx" |
| 131 |
) |
| 132 |
add_custom_command(TARGET doc_pdf POST_BUILD |
| 133 |
COMMAND ${CMAKE_MAKE_PROGRAM} LATEXOPTS=-interaction=batchmode |
| 134 |
WORKING_DIRECTORY "${SPHINX_PDF_DIR}" |
| 135 |
) |
| 136 |
list(APPEND CLEAN_FILES |
| 137 |
"${SPHINX_PDF_DIR}" |
| 138 |
) |
| 139 |
add_dependencies(doc_pdf |
| 140 |
doc_sources |
| 141 |
) |
| 142 |
# serialize Sphinx targets to avoid cache conflicts in parallel builds |
| 143 |
add_dependencies(doc_pdf |
| 144 |
doc_man |
| 145 |
) |
| 146 |
install(FILES "${SPHINX_PDF_DIR}/mydumper.pdf" |
| 147 |
DESTINATION "share/doc/mydumper" |
| 148 |
) |
| 149 |
endif(PDFLATEX_COMPILER) |
| 150 |
|
| 151 |
# Add output directories to clean target. |
| 152 |
set_directory_properties(PROPERTIES |
| 153 |
ADDITIONAL_MAKE_CLEAN_FILES "${CLEAN_FILES}" |
| 154 |
) |
| 155 |
|
| 156 |
endif(GENERATE_DOC) |