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         if(NOT LLVM_ENABLE_IDE)
  75           add_llvm_install_targets("install-${SPHINX_TARGET_NAME}"
  76                                    DEPENDS ${SPHINX_TARGET_NAME}
  77                                    COMPONENT "${project}-sphinx-man")
  78         endif()
  79       elseif (builder STREQUAL html)
  80         string(TOUPPER "${project}" project_upper)
  81         set(${project_upper}_INSTALL_SPHINX_HTML_DIR "share/doc/${project}/html"
  82             CACHE STRING "HTML documentation install directory for ${project}")
  83
  84         # '/.' indicates: copy the contents of the directory directly into
  85         # the specified destination, without recreating the last component
  86         # of ${SPHINX_BUILD_DIR} implicitly.
  87         install(DIRECTORY "${SPHINX_BUILD_DIR}/."
  88                 COMPONENT "${project}-sphinx-html"
  89                 DESTINATION "${${project_upper}_INSTALL_SPHINX_HTML_DIR}")
  90
  91         if(NOT LLVM_ENABLE_IDE)
  92           add_llvm_install_targets("install-${SPHINX_TARGET_NAME}"
  93                                    DEPENDS ${SPHINX_TARGET_NAME}
  94                                    COMPONENT "${project}-sphinx-html")
  95         endif()
  96       else()
  97         message(WARNING Installation of ${builder} not supported)
  98       endif()
  99     endif()
 100   endif()
 101 endfunction()