From 4c464def6ae721b09ebb7cf202e04339267f761a Mon Sep 17 00:00:00 2001
From: Reid Kleckner <reid@kleckner.net>
Date: Fri, 18 Apr 2014 21:45:25 +0000
Subject: 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
---
 cmake/config-ix.cmake               | 10 +++++++
 cmake/modules/AddSphinxTarget.cmake | 54 +++++++++++++++++++++++++++++++++++++
 cmake/modules/FindSphinx.cmake      | 25 +++++++++++++++++
 3 files changed, 89 insertions(+)
 create mode 100644 cmake/modules/AddSphinxTarget.cmake
 create mode 100644 cmake/modules/FindSphinx.cmake

(limited to 'cmake')

diff --git a/cmake/config-ix.cmake b/cmake/config-ix.cmake
index 197caf9355..d1e4b2a64e 100755
--- a/cmake/config-ix.cmake
+++ b/cmake/config-ix.cmake
@@ -505,3 +505,13 @@ if (LLVM_ENABLE_DOXYGEN)
 else()
   message(STATUS "Doxygen disabled.")
 endif()
+
+if (LLVM_ENABLE_SPHINX)
+  message(STATUS "Sphinx enabled.")
+  find_package(Sphinx REQUIRED)
+  if (LLVM_BUILD_DOCS)
+    add_custom_target(sphinx ALL)
+  endif()
+else()
+  message(STATUS "Sphinx disabled.")
+endif()
diff --git a/cmake/modules/AddSphinxTarget.cmake b/cmake/modules/AddSphinxTarget.cmake
new file mode 100644
index 0000000000..1ba77a4d24
--- /dev/null
+++ b/cmake/modules/AddSphinxTarget.cmake
@@ -0,0 +1,54 @@
+# 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)
+  set(SPHINX_BUILD_DIR "${CMAKE_CURRENT_BINARY_DIR}/${builder}")
+  set(SPHINX_DOC_TREE_DIR "${CMAKE_CURRENT_BINARY_DIR}/_doctrees")
+  set(SPHINX_TARGET_NAME docs-${project}-${builder})
+  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.
+                            -W # Warnings are errors.
+                            "${CMAKE_CURRENT_SOURCE_DIR}" # Source
+                            "${SPHINX_BUILD_DIR}" # Output
+                    COMMENT
+                    "Generating ${builder} Sphinx documentation for ${project}")
+
+  # 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 (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
+              DESTINATION share/man/man1)
+
+    elseif (builder STREQUAL html)
+      install(DIRECTORY "${SPHINX_BUILD_DIR}"
+              DESTINATION "share/doc/${project}")
+    else()
+      message(WARNING Installation of ${builder} not supported)
+    endif()
+  endif()
+endfunction()
diff --git a/cmake/modules/FindSphinx.cmake b/cmake/modules/FindSphinx.cmake
new file mode 100644
index 0000000000..a2adcae732
--- /dev/null
+++ b/cmake/modules/FindSphinx.cmake
@@ -0,0 +1,25 @@
+# CMake find_package() Module for Sphinx documentation generator
+# http://sphinx-doc.org/
+#
+# Example usage:
+#
+# find_package(Sphinx)
+#
+# If successful the following variables will be defined
+# SPHINX_FOUND
+# SPHINX_EXECUTABLE
+
+find_program(SPHINX_EXECUTABLE
+             NAMES sphinx-build sphinx-build2
+             DOC "Path to sphinx-build executable")
+
+# Handle REQUIRED and QUIET arguments
+# this will also set SPHINX_FOUND to true if SPHINX_EXECUTABLE exists
+include(FindPackageHandleStandardArgs)
+find_package_handle_standard_args(Sphinx
+                                  "Failed to locate sphinx-build executable"
+                                  SPHINX_EXECUTABLE)
+
+# Provide options for controlling different types of output
+option(SPHINX_OUTPUT_HTML "Output standalone HTML files" ON)
+option(SPHINX_OUTPUT_MAN "Output man pages" ON)
-- 
cgit v1.2.3