llvm/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 #
  21 # Named arguments:
  22 # ``ENV_VARS`` should be a list of environment variables that should be set when
  23 #              running Sphinx. Each environment variable should be a string with
  24 #              the form KEY=VALUE.
  25 function (add_sphinx_target builder project)
  26   cmake_parse_arguments(ARG "" "SOURCE_DIR" "ENV_VARS" ${ARGN})
  27   set(SPHINX_BUILD_DIR "${CMAKE_CURRENT_BINARY_DIR}/${builder}")
  28   set(SPHINX_DOC_TREE_DIR "${CMAKE_CURRENT_BINARY_DIR}/_doctrees-${project}-${builder}")
  29   set(SPHINX_TARGET_NAME docs-${project}-${builder})
  30
  31   if (SPHINX_WARNINGS_AS_ERRORS)
  32     set(SPHINX_WARNINGS_AS_ERRORS_FLAG "-W")
  33   else()
  34     set(SPHINX_WARNINGS_AS_ERRORS_FLAG "")
  35   endif()
  36
  37   if (NOT ARG_SOURCE_DIR)
  38     set(ARG_SOURCE_DIR "${CMAKE_CURRENT_SOURCE_DIR}")
  39   endif()
  40
  41   add_custom_target(${SPHINX_TARGET_NAME}
  42                     COMMAND ${CMAKE_COMMAND} -E env ${ARG_ENV_VARS}
  43                             ${SPHINX_EXECUTABLE}
  44                             -b ${builder}
  45                             -d "${SPHINX_DOC_TREE_DIR}"
  46                             -q # Quiet: no output other than errors and warnings.
  47                             -t builder-${builder} # tag for builder
  48                             ${SPHINX_WARNINGS_AS_ERRORS_FLAG} # Treat warnings as errors if requested
  49                             "${ARG_SOURCE_DIR}" # Source
  50                             "${SPHINX_BUILD_DIR}" # Output
  51                     COMMENT
  52                     "Generating ${builder} Sphinx documentation for ${project} into \"${SPHINX_BUILD_DIR}\"")
  53
  54   # When "clean" target is run, remove the Sphinx build directory
  55   set_property(DIRECTORY APPEND PROPERTY
  56                ADDITIONAL_MAKE_CLEAN_FILES
  57                "${SPHINX_BUILD_DIR}")
  58
  59   # We need to remove ${SPHINX_DOC_TREE_DIR} when make clean is run
  60   # but we should only add this path once
  61   get_property(_CURRENT_MAKE_CLEAN_FILES
  62                DIRECTORY PROPERTY ADDITIONAL_MAKE_CLEAN_FILES)
  63   list(FIND _CURRENT_MAKE_CLEAN_FILES "${SPHINX_DOC_TREE_DIR}" _INDEX)
  64   if (_INDEX EQUAL -1)
  65     set_property(DIRECTORY APPEND PROPERTY
  66                  ADDITIONAL_MAKE_CLEAN_FILES
  67                  "${SPHINX_DOC_TREE_DIR}")
  68   endif()
  69
  70   if (LLVM_BUILD_DOCS)
  71     add_dependencies(sphinx ${SPHINX_TARGET_NAME})
  72
  73     # Handle installation
  74     if (NOT LLVM_INSTALL_TOOLCHAIN_ONLY)
  75       if (builder STREQUAL man)
  76         if (CMAKE_INSTALL_MANDIR)
  77           set(INSTALL_MANDIR ${CMAKE_INSTALL_MANDIR}/)
  78         else()
  79           set(INSTALL_MANDIR share/man/)
  80         endif()
  81         # FIXME: We might not ship all the tools that these man pages describe
  82         install(DIRECTORY "${SPHINX_BUILD_DIR}/" # Slash indicates contents of
  83                 COMPONENT "${project}-sphinx-man"
  84                 DESTINATION ${INSTALL_MANDIR}man1)
  85
  86         if(NOT LLVM_ENABLE_IDE)
  87           add_llvm_install_targets("install-${SPHINX_TARGET_NAME}"
  88                                    DEPENDS ${SPHINX_TARGET_NAME}
  89                                    COMPONENT "${project}-sphinx-man")
  90         endif()
  91       elseif (builder STREQUAL html)
  92         string(TOUPPER "${project}" project_upper)
  93         set(${project_upper}_INSTALL_SPHINX_HTML_DIR "share/doc/${project}/html"
  94             CACHE STRING "HTML documentation install directory for ${project}")
  95
  96         # '/.' indicates: copy the contents of the directory directly into
  97         # the specified destination, without recreating the last component
  98         # of ${SPHINX_BUILD_DIR} implicitly.
  99         install(DIRECTORY "${SPHINX_BUILD_DIR}/."
 100                 COMPONENT "${project}-sphinx-html"
 101                 DESTINATION "${${project_upper}_INSTALL_SPHINX_HTML_DIR}")
 102
 103         if(NOT LLVM_ENABLE_IDE)
 104           add_llvm_install_targets("install-${SPHINX_TARGET_NAME}"
 105                                    DEPENDS ${SPHINX_TARGET_NAME}
 106                                    COMPONENT "${project}-sphinx-html")
 107         endif()
 108       else()
 109         message(WARNING Installation of ${builder} not supported)
 110       endif()
 111     endif()
 112   endif()
 113 endfunction()