1 2# Create sphinx target 3if (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() 9else() 10 message(STATUS "Sphinx disabled.") 11endif() 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. 25function (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() 113endfunction() 114