cmake/modules/AddSphinxTarget.cmake

   1
   2 # Create sphinx target
   3 if (LLVM_ENABLE_SPHINX)
   4   message(STATUS "Sphinx enabled.")
   5   find_package(Sphinx REQUIRED)
   6   if (LLVM_BUILD_DOCS AND NOT TARGET sphinx)
   7     add_custom_target(sphinx ALL)
   8   endif()
   9 else()
  10   message(STATUS "Sphinx disabled.")
  11 endif()
  12
  13
  14 # Handy function for creating the different Sphinx targets.
  15 #
  16 # ``builder`` should be one of the supported builders used by
  17 # the sphinx-build command.
  18 #
  19 # ``project`` should be the project name
  20 function (add_sphinx_target builder project)
  21   set(SPHINX_BUILD_DIR "${CMAKE_CURRENT_BINARY_DIR}/${builder}")
  22   set(SPHINX_DOC_TREE_DIR "${CMAKE_CURRENT_BINARY_DIR}/_doctrees-${project}-${builder}")
  23   set(SPHINX_TARGET_NAME docs-${project}-${builder})
  24
  25   if (SPHINX_WARNINGS_AS_ERRORS)
  26     set(SPHINX_WARNINGS_AS_ERRORS_FLAG "-W")
  27   else()
  28     set(SPHINX_WARNINGS_AS_ERRORS_FLAG "")
  29   endif()
  30
  31   add_custom_target(${SPHINX_TARGET_NAME}
  32                     COMMAND ${SPHINX_EXECUTABLE}
  33                             -b ${builder}
  34                             -d "${SPHINX_DOC_TREE_DIR}"
  35                             -q # Quiet: no output other than errors and warnings.
  36                             ${SPHINX_WARNINGS_AS_ERRORS_FLAG} # Treat warnings as errors if requested
  37                             "${CMAKE_CURRENT_SOURCE_DIR}" # Source
  38                             "${SPHINX_BUILD_DIR}" # Output
  39                     COMMENT
  40                     "Generating ${builder} Sphinx documentation for ${project} into \"${SPHINX_BUILD_DIR}\"")
  41
  42   # When "clean" target is run, remove the Sphinx build directory
  43   set_property(DIRECTORY APPEND PROPERTY
  44                ADDITIONAL_MAKE_CLEAN_FILES
  45                "${SPHINX_BUILD_DIR}")
  46
  47   # We need to remove ${SPHINX_DOC_TREE_DIR} when make clean is run
  48   # but we should only add this path once
  49   get_property(_CURRENT_MAKE_CLEAN_FILES
  50                DIRECTORY PROPERTY ADDITIONAL_MAKE_CLEAN_FILES)
  51   list(FIND _CURRENT_MAKE_CLEAN_FILES "${SPHINX_DOC_TREE_DIR}" _INDEX)
  52   if (_INDEX EQUAL -1)
  53     set_property(DIRECTORY APPEND PROPERTY
  54                  ADDITIONAL_MAKE_CLEAN_FILES
  55                  "${SPHINX_DOC_TREE_DIR}")
  56   endif()
  57
  58   if (LLVM_BUILD_DOCS)
  59     add_dependencies(sphinx ${SPHINX_TARGET_NAME})
  60
  61     # Handle installation
  62     if (NOT LLVM_INSTALL_TOOLCHAIN_ONLY)
  63       if (builder STREQUAL man)
  64         if (CMAKE_INSTALL_MANDIR)
  65           set(INSTALL_MANDIR ${CMAKE_INSTALL_MANDIR}/)
  66         else()
  67           set(INSTALL_MANDIR share/man/)
  68         endif()
  69         # FIXME: We might not ship all the tools that these man pages describe
  70         install(DIRECTORY "${SPHINX_BUILD_DIR}/" # Slash indicates contents of
  71                 COMPONENT "${project}-sphinx-man"
  72                 DESTINATION ${INSTALL_MANDIR}man1)
  73
  74       elseif (builder STREQUAL html)
  75         string(TOUPPER "${project}" project_upper)
  76         set(${project_upper}_INSTALL_SPHINX_HTML_DIR "share/doc/${project}/html"
  77             CACHE STRING "HTML documentation install directory for ${project}")
  78
  79         # '/.' indicates: copy the contents of the directory directly into
  80         # the specified destination, without recreating the last component
  81         # of ${SPHINX_BUILD_DIR} implicitly.
  82         install(DIRECTORY "${SPHINX_BUILD_DIR}/."
  83                 COMPONENT "${project}-sphinx-html"
  84                 DESTINATION "${${project_upper}_INSTALL_SPHINX_HTML_DIR}")
  85       else()
  86         message(WARNING Installation of ${builder} not supported)
  87       endif()
  88     endif()
  89   endif()
  90 endfunction()