llvm.org GIT mirror llvm / 4c464de
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>! git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@206655 91177308-0d34-0410-b5e6-96231b3b80d8 Reid Kleckner 6 years ago
5 changed file(s) with 106 addition(s) and 1 deletion(s). Raw diff Collapse all Expand all
286286
287287 option (LLVM_BUILD_DOCS "Build the llvm documentation." OFF)
288288 option (LLVM_INCLUDE_DOCS "Generate build targets for llvm documentation." ON)
289 option (LLVM_ENABLE_DOXYGEN "Use doxygen to generate llvm documentation." OFF)
289 option (LLVM_ENABLE_DOXYGEN "Use doxygen to generate llvm API documentation." OFF)
290 option (LLVM_ENABLE_SPHINX "Use Sphinx to generate llvm documentation." OFF)
290291
291292 option (LLVM_BUILD_EXTERNAL_COMPILER_RT
292293 "Build compiler-rt as an external project." OFF)
504504 else()
505505 message(STATUS "Doxygen disabled.")
506506 endif()
507
508 if (LLVM_ENABLE_SPHINX)
509 message(STATUS "Sphinx enabled.")
510 find_package(Sphinx REQUIRED)
511 if (LLVM_BUILD_DOCS)
512 add_custom_target(sphinx ALL)
513 endif()
514 else()
515 message(STATUS "Sphinx disabled.")
516 endif()
0 # Handy function for creating the different Sphinx targets.
1 #
2 # ``builder`` should be one of the supported builders used by
3 # the sphinx-build command.
4 #
5 # ``project`` should be the project name
6 function (add_sphinx_target builder project)
7 set(SPHINX_BUILD_DIR "${CMAKE_CURRENT_BINARY_DIR}/${builder}")
8 set(SPHINX_DOC_TREE_DIR "${CMAKE_CURRENT_BINARY_DIR}/_doctrees")
9 set(SPHINX_TARGET_NAME docs-${project}-${builder})
10 add_custom_target(${SPHINX_TARGET_NAME}
11 COMMAND ${SPHINX_EXECUTABLE}
12 -b ${builder}
13 -d "${SPHINX_DOC_TREE_DIR}"
14 -q # Quiet: no output other than errors and warnings.
15 -W # Warnings are errors.
16 "${CMAKE_CURRENT_SOURCE_DIR}" # Source
17 "${SPHINX_BUILD_DIR}" # Output
18 COMMENT
19 "Generating ${builder} Sphinx documentation for ${project}")
20
21 # When "clean" target is run, remove the Sphinx build directory
22 set_property(DIRECTORY APPEND PROPERTY
23 ADDITIONAL_MAKE_CLEAN_FILES
24 "${SPHINX_BUILD_DIR}")
25
26 # We need to remove ${SPHINX_DOC_TREE_DIR} when make clean is run
27 # but we should only add this path once
28 get_property(_CURRENT_MAKE_CLEAN_FILES
29 DIRECTORY PROPERTY ADDITIONAL_MAKE_CLEAN_FILES)
30 list(FIND _CURRENT_MAKE_CLEAN_FILES "${SPHINX_DOC_TREE_DIR}" _INDEX)
31 if (_INDEX EQUAL -1)
32 set_property(DIRECTORY APPEND PROPERTY
33 ADDITIONAL_MAKE_CLEAN_FILES
34 "${SPHINX_DOC_TREE_DIR}")
35 endif()
36
37 if (LLVM_BUILD_DOCS)
38 add_dependencies(sphinx ${SPHINX_TARGET_NAME})
39
40 # Handle installation
41 if (builder STREQUAL man)
42 # FIXME: We might not ship all the tools that these man pages describe
43 install(DIRECTORY "${SPHINX_BUILD_DIR}/" # Slash indicates contents of
44 DESTINATION share/man/man1)
45
46 elseif (builder STREQUAL html)
47 install(DIRECTORY "${SPHINX_BUILD_DIR}"
48 DESTINATION "share/doc/${project}")
49 else()
50 message(WARNING Installation of ${builder} not supported)
51 endif()
52 endif()
53 endfunction()
0 # CMake find_package() Module for Sphinx documentation generator
1 # http://sphinx-doc.org/
2 #
3 # Example usage:
4 #
5 # find_package(Sphinx)
6 #
7 # If successful the following variables will be defined
8 # SPHINX_FOUND
9 # SPHINX_EXECUTABLE
10
11 find_program(SPHINX_EXECUTABLE
12 NAMES sphinx-build sphinx-build2
13 DOC "Path to sphinx-build executable")
14
15 # Handle REQUIRED and QUIET arguments
16 # this will also set SPHINX_FOUND to true if SPHINX_EXECUTABLE exists
17 include(FindPackageHandleStandardArgs)
18 find_package_handle_standard_args(Sphinx
19 "Failed to locate sphinx-build executable"
20 SPHINX_EXECUTABLE)
21
22 # Provide options for controlling different types of output
23 option(SPHINX_OUTPUT_HTML "Output standalone HTML files" ON)
24 option(SPHINX_OUTPUT_MAN "Output man pages" ON)
8888 endif()
8989 endif()
9090 endif()
91
92 if (LLVM_ENABLE_SPHINX)
93 if (SPHINX_FOUND)
94 include(AddSphinxTarget)
95 if (${SPHINX_OUTPUT_HTML})
96 add_sphinx_target(html llvm)
97 endif()
98
99
100 if (${SPHINX_OUTPUT_MAN})
101 add_sphinx_target(man llvm)
102 endif()
103
104 endif()
105 endif()