mirror of
https://github.com/RPCS3/llvm-mirror.git
synced 2024-11-24 11:42:57 +01:00
00be3f56b9
Summary: This is an attempt to simply the process of building the clang documentation, which should help avoid some of the recent issues we've had generating the documentation for the website. The html documentation for clang is generated by sphinx from the reStructuredText (rst) files we have in the clang/docs directory. There are also some rst files that need to be generated by TableGen, before they can be passed to sphinx. Prior to this patch we were not generating those rst files as part with the build system and they had to be generated manually. This patch enables the automatic generation of these rst files, but since they are generated at build time the cannot be placed in the clang/docs directory and must go into the cmake build directory. Unfortunately sphinx does not currently support multiple source directories[1], so in order to be able to generate the full documentation, we need to work around this by copying the rst files from the clang/docs into the build directory before generating the html documentation. [1] https://github.com/sphinx-doc/sphinx/issues/3132 Reviewers: rsmith, aaron.ballman, beanz, smeenai, phosek, compnerd, mgorny, delcypher Reviewed By: mgorny, delcypher Subscribers: delcypher, merge_guards_bot, mgorny, llvm-commits, cfe-commits Tags: #clang, #llvm Differential Revision: https://reviews.llvm.org/D72875
107 lines
4.0 KiB
CMake
107 lines
4.0 KiB
CMake
|
|
# Create sphinx target
|
|
if (LLVM_ENABLE_SPHINX)
|
|
message(STATUS "Sphinx enabled.")
|
|
find_package(Sphinx REQUIRED)
|
|
if (LLVM_BUILD_DOCS AND NOT TARGET sphinx)
|
|
add_custom_target(sphinx ALL)
|
|
endif()
|
|
else()
|
|
message(STATUS "Sphinx disabled.")
|
|
endif()
|
|
|
|
|
|
# Handy function for creating the different Sphinx targets.
|
|
#
|
|
# ``builder`` should be one of the supported builders used by
|
|
# the sphinx-build command.
|
|
#
|
|
# ``project`` should be the project name
|
|
function (add_sphinx_target builder project)
|
|
cmake_parse_arguments(ARG "" "SOURCE_DIR" "" ${ARGN})
|
|
set(SPHINX_BUILD_DIR "${CMAKE_CURRENT_BINARY_DIR}/${builder}")
|
|
set(SPHINX_DOC_TREE_DIR "${CMAKE_CURRENT_BINARY_DIR}/_doctrees-${project}-${builder}")
|
|
set(SPHINX_TARGET_NAME docs-${project}-${builder})
|
|
|
|
if (SPHINX_WARNINGS_AS_ERRORS)
|
|
set(SPHINX_WARNINGS_AS_ERRORS_FLAG "-W")
|
|
else()
|
|
set(SPHINX_WARNINGS_AS_ERRORS_FLAG "")
|
|
endif()
|
|
|
|
if (NOT ARG_SOURCE_DIR)
|
|
set(ARG_SOURCE_DIR "${CMAKE_CURRENT_SOURCE_DIR}")
|
|
endif()
|
|
|
|
add_custom_target(${SPHINX_TARGET_NAME}
|
|
COMMAND ${SPHINX_EXECUTABLE}
|
|
-b ${builder}
|
|
-d "${SPHINX_DOC_TREE_DIR}"
|
|
-q # Quiet: no output other than errors and warnings.
|
|
${SPHINX_WARNINGS_AS_ERRORS_FLAG} # Treat warnings as errors if requested
|
|
"${ARG_SOURCE_DIR}" # Source
|
|
"${SPHINX_BUILD_DIR}" # Output
|
|
COMMENT
|
|
"Generating ${builder} Sphinx documentation for ${project} into \"${SPHINX_BUILD_DIR}\"")
|
|
|
|
# When "clean" target is run, remove the Sphinx build directory
|
|
set_property(DIRECTORY APPEND PROPERTY
|
|
ADDITIONAL_MAKE_CLEAN_FILES
|
|
"${SPHINX_BUILD_DIR}")
|
|
|
|
# We need to remove ${SPHINX_DOC_TREE_DIR} when make clean is run
|
|
# but we should only add this path once
|
|
get_property(_CURRENT_MAKE_CLEAN_FILES
|
|
DIRECTORY PROPERTY ADDITIONAL_MAKE_CLEAN_FILES)
|
|
list(FIND _CURRENT_MAKE_CLEAN_FILES "${SPHINX_DOC_TREE_DIR}" _INDEX)
|
|
if (_INDEX EQUAL -1)
|
|
set_property(DIRECTORY APPEND PROPERTY
|
|
ADDITIONAL_MAKE_CLEAN_FILES
|
|
"${SPHINX_DOC_TREE_DIR}")
|
|
endif()
|
|
|
|
if (LLVM_BUILD_DOCS)
|
|
add_dependencies(sphinx ${SPHINX_TARGET_NAME})
|
|
|
|
# Handle installation
|
|
if (NOT LLVM_INSTALL_TOOLCHAIN_ONLY)
|
|
if (builder STREQUAL man)
|
|
if (CMAKE_INSTALL_MANDIR)
|
|
set(INSTALL_MANDIR ${CMAKE_INSTALL_MANDIR}/)
|
|
else()
|
|
set(INSTALL_MANDIR share/man/)
|
|
endif()
|
|
# FIXME: We might not ship all the tools that these man pages describe
|
|
install(DIRECTORY "${SPHINX_BUILD_DIR}/" # Slash indicates contents of
|
|
COMPONENT "${project}-sphinx-man"
|
|
DESTINATION ${INSTALL_MANDIR}man1)
|
|
|
|
if(NOT LLVM_ENABLE_IDE)
|
|
add_llvm_install_targets("install-${SPHINX_TARGET_NAME}"
|
|
DEPENDS ${SPHINX_TARGET_NAME}
|
|
COMPONENT "${project}-sphinx-man")
|
|
endif()
|
|
elseif (builder STREQUAL html)
|
|
string(TOUPPER "${project}" project_upper)
|
|
set(${project_upper}_INSTALL_SPHINX_HTML_DIR "share/doc/${project}/html"
|
|
CACHE STRING "HTML documentation install directory for ${project}")
|
|
|
|
# '/.' indicates: copy the contents of the directory directly into
|
|
# the specified destination, without recreating the last component
|
|
# of ${SPHINX_BUILD_DIR} implicitly.
|
|
install(DIRECTORY "${SPHINX_BUILD_DIR}/."
|
|
COMPONENT "${project}-sphinx-html"
|
|
DESTINATION "${${project_upper}_INSTALL_SPHINX_HTML_DIR}")
|
|
|
|
if(NOT LLVM_ENABLE_IDE)
|
|
add_llvm_install_targets("install-${SPHINX_TARGET_NAME}"
|
|
DEPENDS ${SPHINX_TARGET_NAME}
|
|
COMPONENT "${project}-sphinx-html")
|
|
endif()
|
|
else()
|
|
message(WARNING Installation of ${builder} not supported)
|
|
endif()
|
|
endif()
|
|
endif()
|
|
endfunction()
|