Cold-Air-Networks/mirror-llvm-project
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 7
mirror-llvm-project/llvm/cmake/modules/AddSphinxTarget.cmake

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

120 lines
4.8 KiB
CMake
Raw Normal View History

Simplify AddSphinxTarget.cmake by just including `GNUInstallDirs` See the discussion in D30906 for how it must be robust to downstream projects that might not use `GNUInstallDirs`. I think an easier approach is just to include `GNUInstallDirs` so that we can always rely on it. Looking at its definition in https://gitlab.kitware.com/cmake/cmake/-/blob/master/Modules/GNUInstallDirs.cmake it appears safe to include multiple times. I am trying this out because we will face the same problem many times over if we use `GNUInstallDirs` more widely, as proposed in D99484 and its parent revisions, since we do not know what downstream projects do and rather not break them. Reviewed By: phosek Differential Revision: https://reviews.llvm.org/D115601
2021-12-12 08:07:13 -09:00
include(GNUInstallDirs)
Revert "Revert "CMake: Move sphinx detection into AddSphinxTarget.cmake"" This reverts commit r302054. Re-commit now that I have fixes for clang/lld. llvm-svn: 302499
2017-05-08 17:41:28 -08:00
# Create sphinx target
CMake: Fix docs-llvm-man target when clang+llvm is in the same source tree Summary: This was broken by r302499. Configuring with -DLLVM_BUILD_DOCS=ON would cause the docs-llvm-man target not to be created. Reviewers: anemet, beanz Reviewed By: anemet Subscribers: llvm-commits, mgorny Differential Revision: https://reviews.llvm.org/D33146 llvm-svn: 303042
2017-05-15 01:34:23 -08:00
if (LLVM_ENABLE_SPHINX)
Revert "Revert "CMake: Move sphinx detection into AddSphinxTarget.cmake"" This reverts commit r302054. Re-commit now that I have fixes for clang/lld. llvm-svn: 302499
2017-05-08 17:41:28 -08:00
message(STATUS "Sphinx enabled.")
find_package(Sphinx REQUIRED)
CMake: Fix docs-llvm-man target when clang+llvm is in the same source tree Summary: This was broken by r302499. Configuring with -DLLVM_BUILD_DOCS=ON would cause the docs-llvm-man target not to be created. Reviewers: anemet, beanz Reviewed By: anemet Subscribers: llvm-commits, mgorny Differential Revision: https://reviews.llvm.org/D33146 llvm-svn: 303042
2017-05-15 01:34:23 -08:00
if (LLVM_BUILD_DOCS AND NOT TARGET sphinx)
Revert "Revert "CMake: Move sphinx detection into AddSphinxTarget.cmake"" This reverts commit r302054. Re-commit now that I have fixes for clang/lld. llvm-svn: 302499
2017-05-08 17:41:28 -08:00
add_custom_target(sphinx ALL)
[llvm] Revise IDE folder structure (#89741) Update the folder titles for targets in the monorepository that have not seen taken care of for some time. These are the folders that targets are organized in Visual Studio and XCode (`set_property(TARGET <target> PROPERTY FOLDER "<title>")`) when using the respective CMake's IDE generator. * Ensure that every target is in a folder * Use a folder hierarchy with each LLVM subproject as a top-level folder * Use consistent folder names between subprojects * When using target-creating functions from AddLLVM.cmake, automatically deduce the folder. This reduces the number of `set_property`/`set_target_property`, but are still necessary when `add_custom_target`, `add_executable`, `add_library`, etc. are used. A LLVM_SUBPROJECT_TITLE definition is used for that in each subproject's root CMakeLists.txt.
2024-05-25 03:28:30 -08:00
set_target_properties(sphinx PROPERTIES FOLDER "LLVM/Docs")
Revert "Revert "CMake: Move sphinx detection into AddSphinxTarget.cmake"" This reverts commit r302054. Re-commit now that I have fixes for clang/lld. llvm-svn: 302499
2017-05-08 17:41:28 -08:00
endif()
else()
message(STATUS "Sphinx disabled.")
endif()
Added Sphinx documentation generation to CMake build system. The option LLVM_ENABLE_SPHINX option enables the "docs-llvm-html", "docs-llvm-man" targets but does not build them by default. The following CMake options have been added that control what targets are made available SPHINX_OUTPUT_HTML SPHINX_OUTPUT_MAN If LLVM_BUILD_DOCS is enabled then the enabled docs-llvm-* targets will be built by default and if ``make install`` is run then docs-llvm-html and docs-llvm-man will be installed (tested on Linux only). The add_sphinx_target function is in its own file so it can be included by other projects that use Sphinx for their documentation. Patch by Daniel Liew <daniel.liew@imperial.ac.uk>! llvm-svn: 206655
2014-04-18 13:45:25 -08:00
# 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
Reland [lldb][docs] Use sphinx instead of epydoc to generate LLDB's Python reference The build server should now have the missing dependencies. Original summary: Currently LLDB uses epydoc to generate the Python API reference for the website. epydoc however is unmaintained since more than a decade and no longer works with Python 3. Also whatever setup we had once for generating the documentation on the website server no longer seems to work, so the current website documentation has been stale since more than a year. This patch replaces epydoc with sphinx and its automodapi plugin that can generate Python API references. LLVM already uses sphinx for the rest of the documentation, so this way we are more consistent with the rest of LLVM. The only new dependency is the automodapi plugin for sphinx. This patch effectively does the following things: * Remove the epydoc code. * Make a new dummy Python API page in our website that just calls the Sphinx command for generated the API documentation. * Add a mock _lldb module that is only used when generating the Python API. This way we don't have to build all of LLDB to generate the API reference. Some notes: * The long list of skips is necessary due to boilerplate functions that SWIG is generating. Sadly automodapi is not really scriptable from what I can see, so we have to blacklist this stuff manually. * The .gitignore change because automodapi wants a subfolder of our documentation directory to place generated documentation files there. The path is also what is used on the website, so we can't really workaround this (without copying the whole `docs` dir somewhere else when we build). * We have to use environment variables to pass our build path to our sphinx configuration. Sphinx doesn't support passing variables onto that script. Reviewed By: JDevlieghere Differential Revision: https://reviews.llvm.org/D94489
2021-01-15 03:24:24 -09:00
#
# 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.
Added Sphinx documentation generation to CMake build system. The option LLVM_ENABLE_SPHINX option enables the "docs-llvm-html", "docs-llvm-man" targets but does not build them by default. The following CMake options have been added that control what targets are made available SPHINX_OUTPUT_HTML SPHINX_OUTPUT_MAN If LLVM_BUILD_DOCS is enabled then the enabled docs-llvm-* targets will be built by default and if ``make install`` is run then docs-llvm-html and docs-llvm-man will be installed (tested on Linux only). The add_sphinx_target function is in its own file so it can be included by other projects that use Sphinx for their documentation. Patch by Daniel Liew <daniel.liew@imperial.ac.uk>! llvm-svn: 206655
2014-04-18 13:45:25 -08:00
function (add_sphinx_target builder project)
Reland [lldb][docs] Use sphinx instead of epydoc to generate LLDB's Python reference The build server should now have the missing dependencies. Original summary: Currently LLDB uses epydoc to generate the Python API reference for the website. epydoc however is unmaintained since more than a decade and no longer works with Python 3. Also whatever setup we had once for generating the documentation on the website server no longer seems to work, so the current website documentation has been stale since more than a year. This patch replaces epydoc with sphinx and its automodapi plugin that can generate Python API references. LLVM already uses sphinx for the rest of the documentation, so this way we are more consistent with the rest of LLVM. The only new dependency is the automodapi plugin for sphinx. This patch effectively does the following things: * Remove the epydoc code. * Make a new dummy Python API page in our website that just calls the Sphinx command for generated the API documentation. * Add a mock _lldb module that is only used when generating the Python API. This way we don't have to build all of LLDB to generate the API reference. Some notes: * The long list of skips is necessary due to boilerplate functions that SWIG is generating. Sadly automodapi is not really scriptable from what I can see, so we have to blacklist this stuff manually. * The .gitignore change because automodapi wants a subfolder of our documentation directory to place generated documentation files there. The path is also what is used on the website, so we can't really workaround this (without copying the whole `docs` dir somewhere else when we build). * We have to use environment variables to pass our build path to our sphinx configuration. Sphinx doesn't support passing variables onto that script. Reviewed By: JDevlieghere Differential Revision: https://reviews.llvm.org/D94489
2021-01-15 03:24:24 -09:00
cmake_parse_arguments(ARG "" "SOURCE_DIR" "ENV_VARS" ${ARGN})
Added Sphinx documentation generation to CMake build system. The option LLVM_ENABLE_SPHINX option enables the "docs-llvm-html", "docs-llvm-man" targets but does not build them by default. The following CMake options have been added that control what targets are made available SPHINX_OUTPUT_HTML SPHINX_OUTPUT_MAN If LLVM_BUILD_DOCS is enabled then the enabled docs-llvm-* targets will be built by default and if ``make install`` is run then docs-llvm-html and docs-llvm-man will be installed (tested on Linux only). The add_sphinx_target function is in its own file so it can be included by other projects that use Sphinx for their documentation. Patch by Daniel Liew <daniel.liew@imperial.ac.uk>! llvm-svn: 206655
2014-04-18 13:45:25 -08:00
set(SPHINX_BUILD_DIR "${CMAKE_CURRENT_BINARY_DIR}/${builder}")
[cmake] Include project name in Sphinx doctree dir to fix race conditions Modify add_sphinx_target() to include the project name alongside builder in Sphinx doctree directory. This aims to avoid crashes due to race conditions between multiple Sphinx instances running in parallel that attempt to create or read that directory simultaneously. This problem has originally been addressed in r283188. However, that commit presumed that there will be only one target per builder being run. However, r314863 introduced a second manpage target, reintroducing the race condition. Differential Revision: https://reviews.llvm.org/D40656 llvm-svn: 319461
2017-11-30 10:09:22 -09:00
set(SPHINX_DOC_TREE_DIR "${CMAKE_CURRENT_BINARY_DIR}/_doctrees-${project}-${builder}")
Added Sphinx documentation generation to CMake build system. The option LLVM_ENABLE_SPHINX option enables the "docs-llvm-html", "docs-llvm-man" targets but does not build them by default. The following CMake options have been added that control what targets are made available SPHINX_OUTPUT_HTML SPHINX_OUTPUT_MAN If LLVM_BUILD_DOCS is enabled then the enabled docs-llvm-* targets will be built by default and if ``make install`` is run then docs-llvm-html and docs-llvm-man will be installed (tested on Linux only). The add_sphinx_target function is in its own file so it can be included by other projects that use Sphinx for their documentation. Patch by Daniel Liew <daniel.liew@imperial.ac.uk>! llvm-svn: 206655
2014-04-18 13:45:25 -08:00
set(SPHINX_TARGET_NAME docs-${project}-${builder})
Add SPHINX_WARNINGS_AS_ERRORS CMake option to allow warnings to not be treated as errors (which is still the default). This is useful when working on documentation that has existing errors. llvm-svn: 215634
2014-08-14 03:57:13 -08:00
if (SPHINX_WARNINGS_AS_ERRORS)
set(SPHINX_WARNINGS_AS_ERRORS_FLAG "-W")
else()
set(SPHINX_WARNINGS_AS_ERRORS_FLAG "")
endif()
[clang][cmake] Include generated rst files in html built by docs-clang-html target 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
2020-03-05 18:57:24 -09:00
if (NOT ARG_SOURCE_DIR)
set(ARG_SOURCE_DIR "${CMAKE_CURRENT_SOURCE_DIR}")
endif()
[docs] Remove hard-coded version numbers from sphinx configs This updates all the non-runtime project release notes to use the version number from CMake instead of the hard-coded version numbers in conf.py. It also hides warnings about pre-releases when the git suffix is dropped from the LLVM version in CMake. Reviewed By: MaskRay Differential Revision: https://reviews.llvm.org/D112181
2022-02-01 22:13:01 -09:00
if ("${LLVM_VERSION_SUFFIX}" STREQUAL "git")
set(PreReleaseTag "-tPreRelease")
endif()
Added Sphinx documentation generation to CMake build system. The option LLVM_ENABLE_SPHINX option enables the "docs-llvm-html", "docs-llvm-man" targets but does not build them by default. The following CMake options have been added that control what targets are made available SPHINX_OUTPUT_HTML SPHINX_OUTPUT_MAN If LLVM_BUILD_DOCS is enabled then the enabled docs-llvm-* targets will be built by default and if ``make install`` is run then docs-llvm-html and docs-llvm-man will be installed (tested on Linux only). The add_sphinx_target function is in its own file so it can be included by other projects that use Sphinx for their documentation. Patch by Daniel Liew <daniel.liew@imperial.ac.uk>! llvm-svn: 206655
2014-04-18 13:45:25 -08:00
add_custom_target(${SPHINX_TARGET_NAME}
Reland [lldb][docs] Use sphinx instead of epydoc to generate LLDB's Python reference The build server should now have the missing dependencies. Original summary: Currently LLDB uses epydoc to generate the Python API reference for the website. epydoc however is unmaintained since more than a decade and no longer works with Python 3. Also whatever setup we had once for generating the documentation on the website server no longer seems to work, so the current website documentation has been stale since more than a year. This patch replaces epydoc with sphinx and its automodapi plugin that can generate Python API references. LLVM already uses sphinx for the rest of the documentation, so this way we are more consistent with the rest of LLVM. The only new dependency is the automodapi plugin for sphinx. This patch effectively does the following things: * Remove the epydoc code. * Make a new dummy Python API page in our website that just calls the Sphinx command for generated the API documentation. * Add a mock _lldb module that is only used when generating the Python API. This way we don't have to build all of LLDB to generate the API reference. Some notes: * The long list of skips is necessary due to boilerplate functions that SWIG is generating. Sadly automodapi is not really scriptable from what I can see, so we have to blacklist this stuff manually. * The .gitignore change because automodapi wants a subfolder of our documentation directory to place generated documentation files there. The path is also what is used on the website, so we can't really workaround this (without copying the whole `docs` dir somewhere else when we build). * We have to use environment variables to pass our build path to our sphinx configuration. Sphinx doesn't support passing variables onto that script. Reviewed By: JDevlieghere Differential Revision: https://reviews.llvm.org/D94489
2021-01-15 03:24:24 -09:00
COMMAND ${CMAKE_COMMAND} -E env ${ARG_ENV_VARS}
[docs] Create utils/docs (#203962) 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
2026-06-24 11:12:48 -08:00
--modify "PYTHONPATH=path_list_append:${LLVM_MAIN_SRC_DIR}/../utils/docs"
Reland [lldb][docs] Use sphinx instead of epydoc to generate LLDB's Python reference The build server should now have the missing dependencies. Original summary: Currently LLDB uses epydoc to generate the Python API reference for the website. epydoc however is unmaintained since more than a decade and no longer works with Python 3. Also whatever setup we had once for generating the documentation on the website server no longer seems to work, so the current website documentation has been stale since more than a year. This patch replaces epydoc with sphinx and its automodapi plugin that can generate Python API references. LLVM already uses sphinx for the rest of the documentation, so this way we are more consistent with the rest of LLVM. The only new dependency is the automodapi plugin for sphinx. This patch effectively does the following things: * Remove the epydoc code. * Make a new dummy Python API page in our website that just calls the Sphinx command for generated the API documentation. * Add a mock _lldb module that is only used when generating the Python API. This way we don't have to build all of LLDB to generate the API reference. Some notes: * The long list of skips is necessary due to boilerplate functions that SWIG is generating. Sadly automodapi is not really scriptable from what I can see, so we have to blacklist this stuff manually. * The .gitignore change because automodapi wants a subfolder of our documentation directory to place generated documentation files there. The path is also what is used on the website, so we can't really workaround this (without copying the whole `docs` dir somewhere else when we build). * We have to use environment variables to pass our build path to our sphinx configuration. Sphinx doesn't support passing variables onto that script. Reviewed By: JDevlieghere Differential Revision: https://reviews.llvm.org/D94489
2021-01-15 03:24:24 -09:00
${SPHINX_EXECUTABLE}
Added Sphinx documentation generation to CMake build system. The option LLVM_ENABLE_SPHINX option enables the "docs-llvm-html", "docs-llvm-man" targets but does not build them by default. The following CMake options have been added that control what targets are made available SPHINX_OUTPUT_HTML SPHINX_OUTPUT_MAN If LLVM_BUILD_DOCS is enabled then the enabled docs-llvm-* targets will be built by default and if ``make install`` is run then docs-llvm-html and docs-llvm-man will be installed (tested on Linux only). The add_sphinx_target function is in its own file so it can be included by other projects that use Sphinx for their documentation. Patch by Daniel Liew <daniel.liew@imperial.ac.uk>! llvm-svn: 206655
2014-04-18 13:45:25 -08:00
-b ${builder}
-d "${SPHINX_DOC_TREE_DIR}"
-q # Quiet: no output other than errors and warnings.
[llvm] [docs] Do not require recommonmark for manpage build Do not enforce recommonmark dependency if sphinx is called to build manpages. In order to do this, try to import recommonmark first and do not configure it if it's not available. Additionally, declare a custom tags for the selected builder via CMake, and ignore recommonmark import failure when 'man' target is used. This will permit us to avoid the problematic recommonmark dependency for the majority of Gentoo users that do not need to locally build the complete documentation but want to have tool manpages. Differential Revision: https://reviews.llvm.org/D83161
2020-07-04 09:23:48 -08:00
-t builder-${builder} # tag for builder
[docs] Remove hard-coded version numbers from sphinx configs This updates all the non-runtime project release notes to use the version number from CMake instead of the hard-coded version numbers in conf.py. It also hides warnings about pre-releases when the git suffix is dropped from the LLVM version in CMake. Reviewed By: MaskRay Differential Revision: https://reviews.llvm.org/D112181
2022-02-01 22:13:01 -09:00
-D version=${LLVM_VERSION_MAJOR}
-D release=${PACKAGE_VERSION}
${PreReleaseTag}
Add SPHINX_WARNINGS_AS_ERRORS CMake option to allow warnings to not be treated as errors (which is still the default). This is useful when working on documentation that has existing errors. llvm-svn: 215634
2014-08-14 03:57:13 -08:00
${SPHINX_WARNINGS_AS_ERRORS_FLAG} # Treat warnings as errors if requested
[clang][cmake] Include generated rst files in html built by docs-clang-html target 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
2020-03-05 18:57:24 -09:00
"${ARG_SOURCE_DIR}" # Source
Added Sphinx documentation generation to CMake build system. The option LLVM_ENABLE_SPHINX option enables the "docs-llvm-html", "docs-llvm-man" targets but does not build them by default. The following CMake options have been added that control what targets are made available SPHINX_OUTPUT_HTML SPHINX_OUTPUT_MAN If LLVM_BUILD_DOCS is enabled then the enabled docs-llvm-* targets will be built by default and if ``make install`` is run then docs-llvm-html and docs-llvm-man will be installed (tested on Linux only). The add_sphinx_target function is in its own file so it can be included by other projects that use Sphinx for their documentation. Patch by Daniel Liew <daniel.liew@imperial.ac.uk>! llvm-svn: 206655
2014-04-18 13:45:25 -08:00
"${SPHINX_BUILD_DIR}" # Output
COMMENT
Make message about building sphinx documentation with CMake more informative by stating where the output is going. llvm-svn: 215635
2014-08-14 03:57:16 -08:00
"Generating ${builder} Sphinx documentation for ${project} into \"${SPHINX_BUILD_DIR}\"")
[llvm] Revise IDE folder structure (#89741) Update the folder titles for targets in the monorepository that have not seen taken care of for some time. These are the folders that targets are organized in Visual Studio and XCode (`set_property(TARGET <target> PROPERTY FOLDER "<title>")`) when using the respective CMake's IDE generator. * Ensure that every target is in a folder * Use a folder hierarchy with each LLVM subproject as a top-level folder * Use consistent folder names between subprojects * When using target-creating functions from AddLLVM.cmake, automatically deduce the folder. This reduces the number of `set_property`/`set_target_property`, but are still necessary when `add_custom_target`, `add_executable`, `add_library`, etc. are used. A LLVM_SUBPROJECT_TITLE definition is used for that in each subproject's root CMakeLists.txt.
2024-05-25 03:28:30 -08:00
get_subproject_title(subproject_title)
set_target_properties(${SPHINX_TARGET_NAME} PROPERTIES FOLDER "${subproject_title}/Docs")
Added Sphinx documentation generation to CMake build system. The option LLVM_ENABLE_SPHINX option enables the "docs-llvm-html", "docs-llvm-man" targets but does not build them by default. The following CMake options have been added that control what targets are made available SPHINX_OUTPUT_HTML SPHINX_OUTPUT_MAN If LLVM_BUILD_DOCS is enabled then the enabled docs-llvm-* targets will be built by default and if ``make install`` is run then docs-llvm-html and docs-llvm-man will be installed (tested on Linux only). The add_sphinx_target function is in its own file so it can be included by other projects that use Sphinx for their documentation. Patch by Daniel Liew <daniel.liew@imperial.ac.uk>! llvm-svn: 206655
2014-04-18 13:45:25 -08:00
# 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)
[CMake] Replace list(FIND) by if(IN_LIST) where index isn't used If we don't use the index otherwise, if(IN_LIST) is more readable and doesn't clutter the local scope with index variables. This was pointed out by @beanz in D96670. Reviewed By: beanz Differential Revision: https://reviews.llvm.org/D142405
2023-01-23 13:58:43 -09:00
if (NOT "${SPHINX_DOC_TREE_DIR}" IN_LIST _CURRENT_MAKE_CLEAN_FILES)
Added Sphinx documentation generation to CMake build system. The option LLVM_ENABLE_SPHINX option enables the "docs-llvm-html", "docs-llvm-man" targets but does not build them by default. The following CMake options have been added that control what targets are made available SPHINX_OUTPUT_HTML SPHINX_OUTPUT_MAN If LLVM_BUILD_DOCS is enabled then the enabled docs-llvm-* targets will be built by default and if ``make install`` is run then docs-llvm-html and docs-llvm-man will be installed (tested on Linux only). The add_sphinx_target function is in its own file so it can be included by other projects that use Sphinx for their documentation. Patch by Daniel Liew <daniel.liew@imperial.ac.uk>! llvm-svn: 206655
2014-04-18 13:45:25 -08:00
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
Teach add_sphinx_target() to respect the LLVM_INSTALL_TOOLCHAIN_ONLY CMake option. llvm-svn: 207450
2014-04-28 14:06:20 -08:00
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
[cmake] Include component in Sphinx install rules Include component in install rules for Sphinx targets. Based on a similar suggestion for other doc targets in D24935. Differential Revision: https://reviews.llvm.org/D24982 llvm-svn: 288656
2016-12-05 00:15:05 -09:00
COMPONENT "${project}-sphinx-man"
Simplify AddSphinxTarget.cmake by just including `GNUInstallDirs` See the discussion in D30906 for how it must be robust to downstream projects that might not use `GNUInstallDirs`. I think an easier approach is just to include `GNUInstallDirs` so that we can always rely on it. Looking at its definition in https://gitlab.kitware.com/cmake/cmake/-/blob/master/Modules/GNUInstallDirs.cmake it appears safe to include multiple times. I am trying this out because we will face the same problem many times over if we use `GNUInstallDirs` more widely, as proposed in D99484 and its parent revisions, since we do not know what downstream projects do and rather not break them. Reviewed By: phosek Differential Revision: https://reviews.llvm.org/D115601
2021-12-12 08:07:13 -09:00
DESTINATION "${CMAKE_INSTALL_MANDIR}/man1")
Added Sphinx documentation generation to CMake build system. The option LLVM_ENABLE_SPHINX option enables the "docs-llvm-html", "docs-llvm-man" targets but does not build them by default. The following CMake options have been added that control what targets are made available SPHINX_OUTPUT_HTML SPHINX_OUTPUT_MAN If LLVM_BUILD_DOCS is enabled then the enabled docs-llvm-* targets will be built by default and if ``make install`` is run then docs-llvm-html and docs-llvm-man will be installed (tested on Linux only). The add_sphinx_target function is in its own file so it can be included by other projects that use Sphinx for their documentation. Patch by Daniel Liew <daniel.liew@imperial.ac.uk>! llvm-svn: 206655
2014-04-18 13:45:25 -08:00
[llvm] [cmake] Add install targets for missing distribution components Add install targets as necessary to include all files normally installed in LLVM_DISTRIBUTION_COMPONENTS. This includes targets for Sphinx docs, opt-viewer Python modules and TableGens. Differential Revision: https://reviews.llvm.org/D68339 llvm-svn: 373482
2019-10-02 08:06:50 -08:00
if(NOT LLVM_ENABLE_IDE)
add_llvm_install_targets("install-${SPHINX_TARGET_NAME}"
DEPENDS ${SPHINX_TARGET_NAME}
COMPONENT "${project}-sphinx-man")
endif()
Teach add_sphinx_target() to respect the LLVM_INSTALL_TOOLCHAIN_ONLY CMake option. llvm-svn: 207450
2014-04-28 14:06:20 -08:00
elseif (builder STREQUAL html)
cmake: Support overriding Sphinx HTML doc install directory Provide ${PROJECT}_INSTALL_SPHINX_HTML_DIR variables (e.g. LLVM_INSTALL_SPHINX_HTML_DIR) to override Sphinx HTML doc install directory. Bug: https://llvm.org/bugs/show_bug.cgi?id=23780 Differential Revision: https://reviews.llvm.org/D23757 llvm-svn: 282240
2016-09-23 03:09:33 -08:00
string(TOUPPER "${project}" project_upper)
[llvm] Use `GNUInstallDirs` to support custom installation dirs This is the patch for LLVM proper in my series for adding GNUInstallDirs support in all project. Additionally: Create a new `CACHE STRING` variable, `LLVM_EXAMPLES_INSTALL_DIR`, to control where the examples are installed on analogy with the other variables. --- This patch supersedes D28234, which tried to do the same thing but hand-rolled without GNUInstallDirs. This patch nearly reverts commit 3 0fc88bf1dc15a72e2d9809d28019d386b7a7cc0, which was a revert of a prior attempt." (I had to add a space here or else Phabricator detects a reference cycle and won't let me do the form submit.) Reviewed By: compnerd Differential Revision: https://reviews.llvm.org/D100810
2021-12-10 16:36:24 -09:00
set(${project_upper}_INSTALL_SPHINX_HTML_DIR "${CMAKE_INSTALL_DOCDIR}/${project}/html"
cmake: Support overriding Sphinx HTML doc install directory Provide ${PROJECT}_INSTALL_SPHINX_HTML_DIR variables (e.g. LLVM_INSTALL_SPHINX_HTML_DIR) to override Sphinx HTML doc install directory. Bug: https://llvm.org/bugs/show_bug.cgi?id=23780 Differential Revision: https://reviews.llvm.org/D23757 llvm-svn: 282240
2016-09-23 03:09:33 -08:00
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}/."
[cmake] Include component in Sphinx install rules Include component in install rules for Sphinx targets. Based on a similar suggestion for other doc targets in D24935. Differential Revision: https://reviews.llvm.org/D24982 llvm-svn: 288656
2016-12-05 00:15:05 -09:00
COMPONENT "${project}-sphinx-html"
cmake: Support overriding Sphinx HTML doc install directory Provide ${PROJECT}_INSTALL_SPHINX_HTML_DIR variables (e.g. LLVM_INSTALL_SPHINX_HTML_DIR) to override Sphinx HTML doc install directory. Bug: https://llvm.org/bugs/show_bug.cgi?id=23780 Differential Revision: https://reviews.llvm.org/D23757 llvm-svn: 282240
2016-09-23 03:09:33 -08:00
DESTINATION "${${project_upper}_INSTALL_SPHINX_HTML_DIR}")
[llvm] [cmake] Add install targets for missing distribution components Add install targets as necessary to include all files normally installed in LLVM_DISTRIBUTION_COMPONENTS. This includes targets for Sphinx docs, opt-viewer Python modules and TableGens. Differential Revision: https://reviews.llvm.org/D68339 llvm-svn: 373482
2019-10-02 08:06:50 -08:00
if(NOT LLVM_ENABLE_IDE)
add_llvm_install_targets("install-${SPHINX_TARGET_NAME}"
DEPENDS ${SPHINX_TARGET_NAME}
COMPONENT "${project}-sphinx-html")
endif()
Teach add_sphinx_target() to respect the LLVM_INSTALL_TOOLCHAIN_ONLY CMake option. llvm-svn: 207450
2014-04-28 14:06:20 -08:00
else()
message(WARNING Installation of ${builder} not supported)
endif()
Added Sphinx documentation generation to CMake build system. The option LLVM_ENABLE_SPHINX option enables the "docs-llvm-html", "docs-llvm-man" targets but does not build them by default. The following CMake options have been added that control what targets are made available SPHINX_OUTPUT_HTML SPHINX_OUTPUT_MAN If LLVM_BUILD_DOCS is enabled then the enabled docs-llvm-* targets will be built by default and if ``make install`` is run then docs-llvm-html and docs-llvm-man will be installed (tested on Linux only). The add_sphinx_target function is in its own file so it can be included by other projects that use Sphinx for their documentation. Patch by Daniel Liew <daniel.liew@imperial.ac.uk>! llvm-svn: 206655
2014-04-18 13:45:25 -08:00
endif()
endif()
endfunction()
Reference in a new issue Copy permalink