Utilities/Sphinx/CMakeLists.txt

   1 # Distributed under the OSI-approved BSD 3-Clause License.  See accompanying
   2 # file Copyright.txt or https://cmake.org/licensing for details.
   3
   4 if(NOT CMake_SOURCE_DIR)
   5   set(CMakeHelp_STANDALONE 1)
   6   cmake_minimum_required(VERSION 3.1...3.21 FATAL_ERROR)
   7   get_filename_component(tmp "${CMAKE_CURRENT_SOURCE_DIR}" PATH)
   8   get_filename_component(CMake_SOURCE_DIR "${tmp}" PATH)
   9   include(${CMake_SOURCE_DIR}/Modules/CTestUseLaunchers.cmake)
  10   include(${CMake_SOURCE_DIR}/Source/CMakeVersion.cmake)
  11   include(${CMake_SOURCE_DIR}/Source/CMakeInstallDestinations.cmake)
  12   configure_file(${CMAKE_CURRENT_SOURCE_DIR}/CTestCustom.cmake.in ${CMAKE_CURRENT_BINARY_DIR}/CTestCustom.cmake @ONLY)
  13   unset(CMAKE_DATA_DIR)
  14   unset(CMAKE_DATA_DIR CACHE)
  15   macro(CMake_OPTIONAL_COMPONENT)
  16     set(COMPONENT "")
  17   endmacro()
  18 endif()
  19 project(CMakeHelp NONE)
  20
  21 option(SPHINX_INFO "Build Info manual with Sphinx" OFF)
  22 option(SPHINX_MAN "Build man pages with Sphinx" OFF)
  23 option(SPHINX_HTML "Build html help with Sphinx" OFF)
  24 option(SPHINX_SINGLEHTML "Build html single page help with Sphinx" OFF)
  25 option(SPHINX_QTHELP "Build Qt help with Sphinx" OFF)
  26 option(SPHINX_LATEXPDF "Build PDF help with Sphinx using LaTeX" OFF)
  27 option(SPHINX_TEXT "Build text help with Sphinx (not installed)" OFF)
  28 find_program(SPHINX_EXECUTABLE
  29   NAMES sphinx-build
  30   DOC "Sphinx Documentation Builder (sphinx-doc.org)"
  31   )
  32 set(SPHINX_FLAGS "" CACHE STRING "Flags to pass to sphinx-build")
  33 separate_arguments(sphinx_flags UNIX_COMMAND "${SPHINX_FLAGS}")
  34
  35 mark_as_advanced(SPHINX_TEXT)
  36 mark_as_advanced(SPHINX_FLAGS)
  37
  38 if(NOT SPHINX_INFO AND NOT SPHINX_MAN AND NOT SPHINX_HTML AND NOT SPHINX_SINGLEHTML AND NOT SPHINX_QTHELP AND NOT SPHINX_TEXT AND NOT SPHINX_LATEXPDF)
  39   return()
  40 elseif(NOT SPHINX_EXECUTABLE)
  41   message(FATAL_ERROR "SPHINX_EXECUTABLE (sphinx-build) is not found!")
  42 endif()
  43
  44 set(copyright_line_regex "^Copyright (2000-20[0-9][0-9] Kitware.*)")
  45 file(STRINGS "${CMake_SOURCE_DIR}/Copyright.txt" copyright_line
  46   LIMIT_COUNT 1 REGEX "${copyright_line_regex}")
  47 if(copyright_line MATCHES "${copyright_line_regex}")
  48   set(conf_copyright "${CMAKE_MATCH_1}")
  49 else()
  50   set(conf_copyright "Kitware, Inc.")
  51 endif()
  52
  53 if(CMake_SPHINX_CMAKE_ORG)
  54   set(conf_baseurl "https://cmake.org/cmake/help/latest")
  55 else()
  56   set(conf_baseurl "")
  57 endif()
  58
  59 set(conf_docs "${CMake_SOURCE_DIR}/Help")
  60 set(conf_path "${CMAKE_CURRENT_SOURCE_DIR}")
  61 set(conf_version "${CMake_VERSION_MAJOR}.${CMake_VERSION_MINOR}.${CMake_VERSION_PATCH}")
  62 set(conf_release "${CMake_VERSION}")
  63 configure_file(conf.py.in conf.py @ONLY)
  64
  65 set(doc_formats "")
  66 if(SPHINX_HTML)
  67   list(APPEND doc_formats html)
  68
  69   # we provide the path to the produced html output in the console
  70   # for tools that support URI protocol schemes
  71   set(html_post_commands
  72     COMMAND ${CMAKE_COMMAND} -E echo "sphinx-build html: HTML documentation generated in file://${CMAKE_CURRENT_BINARY_DIR}/html/index.html"
  73   )
  74
  75 endif()
  76 if(SPHINX_MAN)
  77   list(APPEND doc_formats man)
  78 endif()
  79 if(SPHINX_SINGLEHTML)
  80   list(APPEND doc_formats singlehtml)
  81 endif()
  82 if(SPHINX_TEXT)
  83   list(APPEND doc_formats text)
  84 endif()
  85 if(SPHINX_INFO)
  86   find_program(MAKEINFO_EXECUTABLE
  87     NAMES makeinfo
  88     DOC "makeinfo tool"
  89     )
  90   if (NOT MAKEINFO_EXECUTABLE)
  91     message(FATAL_ERROR "MAKEINFO_EXECUTABLE (makeinfo) not found!")
  92   endif()
  93   list(APPEND doc_formats texinfo)
  94
  95   # Sphinx texinfo builder supports .info, .txt, .html and .pdf output.
  96   # SPHINX_INFO controls the .info output.
  97   set(texinfo_post_commands
  98     COMMAND ${MAKEINFO_EXECUTABLE} --no-split -o
  99       ${CMAKE_CURRENT_BINARY_DIR}/texinfo/cmake.info
 100       ${CMAKE_CURRENT_BINARY_DIR}/texinfo/cmake.texi
 101   )
 102 endif()
 103 if(SPHINX_QTHELP)
 104   find_package(PythonInterp REQUIRED)
 105
 106   find_program(QHELPGENERATOR_EXECUTABLE
 107     NAMES qhelpgenerator-qt5 qhelpgenerator
 108     DOC "qhelpgenerator tool"
 109     )
 110   if(NOT QHELPGENERATOR_EXECUTABLE)
 111     message(FATAL_ERROR "QHELPGENERATOR_EXECUTABLE (qhelpgenerator) not found!")
 112   endif()
 113   list(APPEND doc_formats qthelp)
 114
 115   set(qthelp_post_commands
 116     # Workaround for assistant prior to
 117     # https://codereview.qt-project.org/#change,82250 in Qt 4.
 118     COMMAND ${CMAKE_COMMAND} "-DCSS_DIR=${CMAKE_CURRENT_BINARY_DIR}/qthelp/_static"
 119       -P "${CMAKE_CURRENT_SOURCE_DIR}/apply_qthelp_css_workaround.cmake"
 120     # Workaround sphinx configurability:
 121     # https://bitbucket.org/birkenfeld/sphinx/issue/1448/make-qthelp-more-configurable
 122     COMMAND ${CMAKE_COMMAND} "-DQTHELP_DIR=${CMAKE_CURRENT_BINARY_DIR}/qthelp/"
 123       -P "${CMAKE_CURRENT_SOURCE_DIR}/fixup_qthelp_names.cmake"
 124
 125     # Create proper identifiers. Workaround for
 126     # https://bitbucket.org/birkenfeld/sphinx/issue/1491/qthelp-should-generate-identifiers-for
 127     COMMAND "${PYTHON_EXECUTABLE}"
 128       "${CMAKE_CURRENT_SOURCE_DIR}/create_identifiers.py"
 129       "${CMAKE_CURRENT_BINARY_DIR}/qthelp/"
 130
 131     COMMAND ${QHELPGENERATOR_EXECUTABLE}
 132       ${CMAKE_CURRENT_BINARY_DIR}/qthelp/CMake.qhcp
 133   )
 134 endif()
 135 if(SPHINX_LATEXPDF)
 136   list(APPEND doc_formats latexpdf)
 137 endif()
 138
 139 set(doc_html_opts "")
 140 if(CMake_SPHINX_CMAKE_ORG)
 141   list(APPEND doc_html_opts
 142     -A googleanalytics=1
 143     -A opensearch=1
 144     -A versionswitch=1
 145     )
 146
 147   if(CMake_SPHINX_CMAKE_ORG_OUTDATED)
 148     list(APPEND doc_html_opts -A outdated=1)
 149   endif()
 150
 151   list(APPEND html_pre_commands
 152     COMMAND ${CMAKE_COMMAND} -Dversion=${CMake_VERSION} -P ${CMAKE_CURRENT_SOURCE_DIR}/tutorial_archive.cmake
 153     )
 154
 155   list(APPEND qthelp_post_commands
 156     COMMAND ${CMAKE_COMMAND} -E copy
 157       "${CMAKE_CURRENT_BINARY_DIR}/qthelp/CMake.qch"
 158       "${CMAKE_CURRENT_BINARY_DIR}/html/CMake.qch"
 159     )
 160 endif()
 161
 162 set(doc_format_outputs "")
 163 set(doc_format_last "")
 164 foreach(format ${doc_formats})
 165   set(doc_format_output "doc_format_${format}")
 166   set(doc_format_log "build-${format}.log")
 167   if(CMake_SPHINX_CMAKE_ORG)
 168     set(doctrees "doctrees/${format}")
 169   else()
 170     set(doctrees "doctrees")
 171   endif()
 172   if(format STREQUAL "latexpdf")
 173     # This format does not use builder (-b) but make_mode (-M) which expects
 174     # arguments in peculiar order
 175     add_custom_command(
 176       OUTPUT ${doc_format_output}
 177       ${${format}_pre_commands}
 178       COMMAND ${SPHINX_EXECUTABLE}
 179               -M ${format}
 180               ${CMake_SOURCE_DIR}/Help
 181               ${CMAKE_CURRENT_BINARY_DIR}/${format}
 182               -c ${CMAKE_CURRENT_BINARY_DIR}
 183               -d ${CMAKE_CURRENT_BINARY_DIR}/${doctrees}
 184               ${sphinx_flags}
 185               ${doc_${format}_opts}
 186               > ${doc_format_log} # log stdout, pass stderr
 187       ${${format}_post_commands}
 188       DEPENDS ${doc_format_last}
 189       COMMENT "sphinx-build ${format}: see Utilities/Sphinx/${doc_format_log}"
 190       VERBATIM
 191       )
 192   else()
 193     # other formats use standard builder (-b) mode
 194     add_custom_command(
 195       OUTPUT ${doc_format_output}
 196       ${${format}_pre_commands}
 197       COMMAND ${SPHINX_EXECUTABLE}
 198               -c ${CMAKE_CURRENT_BINARY_DIR}
 199               -d ${CMAKE_CURRENT_BINARY_DIR}/${doctrees}
 200               -b ${format}
 201               ${sphinx_flags}
 202               ${doc_${format}_opts}
 203               ${CMake_SOURCE_DIR}/Help
 204               ${CMAKE_CURRENT_BINARY_DIR}/${format}
 205               > ${doc_format_log} # log stdout, pass stderr
 206       ${${format}_post_commands}
 207       DEPENDS ${doc_format_last}
 208       COMMENT "sphinx-build ${format}: see Utilities/Sphinx/${doc_format_log}"
 209       VERBATIM
 210       )
 211   endif()
 212   set_property(SOURCE ${doc_format_output} PROPERTY SYMBOLIC 1)
 213   list(APPEND doc_format_outputs ${doc_format_output})
 214   if(NOT CMake_SPHINX_CMAKE_ORG)
 215     set(doc_format_last ${doc_format_output})
 216   endif()
 217 endforeach()
 218
 219 add_custom_target(documentation ALL DEPENDS ${doc_format_outputs})
 220
 221 if(CMake_SPHINX_DEPEND_ON_EXECUTABLES)
 222   foreach(t
 223       cmake
 224       ccmake
 225       cmake-gui
 226       cpack
 227       ctest
 228       )
 229     if(TARGET ${t})
 230       # Build documentation after main executables.
 231       add_dependencies(documentation ${t})
 232     endif()
 233   endforeach()
 234 endif()
 235
 236 if(CMake_SPHINX_CMAKE_ORG)
 237   return()
 238 endif()
 239
 240 if(SPHINX_INFO)
 241   CMake_OPTIONAL_COMPONENT(sphinx-info)
 242   install(FILES ${CMAKE_CURRENT_BINARY_DIR}/texinfo/cmake.info
 243           DESTINATION ${CMAKE_INFO_DIR}
 244           ${COMPONENT}
 245           )
 246 endif()
 247
 248 if(SPHINX_MAN)
 249   file(GLOB man_rst RELATIVE ${CMake_SOURCE_DIR}/Help/manual
 250     ${CMake_SOURCE_DIR}/Help/manual/*.[1-9].rst)
 251   foreach(m ${man_rst})
 252     if("x${m}" MATCHES "^x(.+)\\.([1-9])\\.rst$")
 253       set(name "${CMAKE_MATCH_1}")
 254       set(sec "${CMAKE_MATCH_2}")
 255       set(skip FALSE)
 256       if(NOT CMakeHelp_STANDALONE)
 257         if(name STREQUAL "ccmake" AND NOT BUILD_CursesDialog)
 258           set(skip TRUE)
 259         elseif(name STREQUAL "cmake-gui" AND NOT BUILD_QtDialog)
 260           set(skip TRUE)
 261         endif()
 262       endif()
 263       if(NOT skip)
 264         CMake_OPTIONAL_COMPONENT(sphinx-man)
 265         install(FILES ${CMAKE_CURRENT_BINARY_DIR}/man/${name}.${sec}
 266                 DESTINATION ${CMAKE_MAN_DIR}/man${sec}
 267                 ${COMPONENT})
 268       endif()
 269       unset(skip)
 270     endif()
 271   endforeach()
 272 endif()
 273
 274 if(SPHINX_HTML)
 275   CMake_OPTIONAL_COMPONENT(sphinx-html)
 276   install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/html
 277           DESTINATION ${CMAKE_DOC_DIR}
 278           ${COMPONENT}
 279           PATTERN .buildinfo EXCLUDE
 280           )
 281 endif()
 282
 283 if(SPHINX_SINGLEHTML)
 284   CMake_OPTIONAL_COMPONENT(sphinx-singlehtml)
 285   install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/singlehtml
 286           DESTINATION ${CMAKE_DOC_DIR}
 287           ${COMPONENT}
 288           PATTERN .buildinfo EXCLUDE
 289           )
 290 endif()
 291
 292 if(SPHINX_QTHELP)
 293   CMake_OPTIONAL_COMPONENT(sphinx-qthelp)
 294   install(FILES ${CMAKE_CURRENT_BINARY_DIR}/qthelp/CMake.qch
 295           DESTINATION ${CMAKE_DOC_DIR} ${COMPONENT}
 296           )
 297 endif()
 298
 299 if(SPHINX_LATEXPDF)
 300   CMake_OPTIONAL_COMPONENT(sphinx-latexpdf)
 301   install(FILES ${CMAKE_CURRENT_BINARY_DIR}/latexpdf/latex/CMake.pdf
 302           DESTINATION ${CMAKE_DOC_DIR} ${COMPONENT}
 303           )
 304 endif()