42ff45b865
llvm-project is home to many sphinx documentation sites, each with configuration quirks and bespoke extensions. The sphinx config model makes sharing code somewhat difficult. There are options like sphinx-multiproject, but some of our docs builds are out of the source tree while some are done out of the binary tree, so the multiproject configuration itself would need to be generated. It also would impose more uniformity around extensions than required. This change instead creates a python package at utils/docs/llvm_sphinx and makes it available to all sphinx-build processes via PYTHONPATH. Each conf.py does not modify its own sys.path because not all builds are out of the source tree, so there isn't a stable relative path to use to refer to the utils/docs/ directory. Type checking via pyright in new package is pinned to being python 3.8 compatible. The myst slug script from llvm/docs is promoted to be the default, with a slight edit to targets needed in FlangDriver.md to adapt to the change. The ghlinks extension from clang gets lifted to be the first generic extension, although it is still only used in clang currently. I used it as an example of a general extension that might be useful for other projects, but I also intend to add a new generic extension in a future patch. As part of the move ghlinks is refactored a bit: * Rather than have a main function directly to run its tests, those tests are now run via the command-line entrypoint to the new package, e.g. `python utils/docs --test` will now replace `python clang/docs/ghlinks.py --test`. This makes the command-line more pithy (`python utils/docs/llvm_sphinx/ext/ghlinks --test` is a bit long), and makes the default behavior when running be to include utils/docs in the sys.path, so imports can be absolute and the behavior is as close to the CMake targets as possible. * The static files that were previously written to a tempdir during testing are just committed directly in git. The assumption here is that the original version was taking pains to avoid polluting the clang/docs directory with test files that would confuse sphinx-build, and without that limitation the workaround can be removed. * Some typing-related changes to make it strictly python 3.8 compatible. Change-Id: Ie16de273f74973f163dbf7fe9d22d80a466d051f
119 lines
4.8 KiB
CMake
119 lines
4.8 KiB
CMake
include(GNUInstallDirs)
|
|
|
|
# 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)
|
|
set_target_properties(sphinx PROPERTIES FOLDER "LLVM/Docs")
|
|
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
|
|
#
|
|
# Named arguments:
|
|
# ``ENV_VARS`` should be a list of environment variables that should be set when
|
|
# running Sphinx. Each environment variable should be a string with
|
|
# the form KEY=VALUE.
|
|
function (add_sphinx_target builder project)
|
|
cmake_parse_arguments(ARG "" "SOURCE_DIR" "ENV_VARS" ${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()
|
|
|
|
if ("${LLVM_VERSION_SUFFIX}" STREQUAL "git")
|
|
set(PreReleaseTag "-tPreRelease")
|
|
endif()
|
|
|
|
add_custom_target(${SPHINX_TARGET_NAME}
|
|
COMMAND ${CMAKE_COMMAND} -E env ${ARG_ENV_VARS}
|
|
--modify "PYTHONPATH=path_list_append:${LLVM_MAIN_SRC_DIR}/../utils/docs"
|
|
${SPHINX_EXECUTABLE}
|
|
-b ${builder}
|
|
-d "${SPHINX_DOC_TREE_DIR}"
|
|
-q # Quiet: no output other than errors and warnings.
|
|
-t builder-${builder} # tag for builder
|
|
-D version=${LLVM_VERSION_MAJOR}
|
|
-D release=${PACKAGE_VERSION}
|
|
${PreReleaseTag}
|
|
${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}\"")
|
|
get_subproject_title(subproject_title)
|
|
set_target_properties(${SPHINX_TARGET_NAME} PROPERTIES FOLDER "${subproject_title}/Docs")
|
|
|
|
# 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)
|
|
if (NOT "${SPHINX_DOC_TREE_DIR}" IN_LIST _CURRENT_MAKE_CLEAN_FILES)
|
|
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)
|
|
# 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 "${CMAKE_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 "${CMAKE_INSTALL_DOCDIR}/${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()
|