Rework the Sphinx find module

* Make sphinx_rtd_theme a find module component to avoid hard-wiring it
  into the module and allowing to report the theme in case it is missing
  using the standard CMake package mechanism.
* Adjust find module cache variables names case to match the find module
  name.
* Also report sphinx-build version for completeness.
* Invoke the find module only once. Calling find_package on the same
  module is not needed.

Change-Id: I9d1bf0fcc0d44b9b37e624128812f348c5442ada

CMakeLists.txt

diff --git a/CMakeLists.txt b/CMakeLists.txt
index 2957e60..91cf6b1 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -622,8 +622,8 @@
 add_subdirectory(internal/ceres)
 
 if (BUILD_DOCUMENTATION)
-  find_package(Sphinx)
-  if (NOT SPHINX_FOUND)
+  find_package (Sphinx REQUIRED COMPONENTS sphinx_rtd_theme)
+  if (NOT Sphinx_FOUND)
     message("-- Failed to find Sphinx and/or its dependencies, disabling build of documentation.")
     update_cache_variable(BUILD_DOCUMENTATION OFF)
   else()

cmake/FindSphinx.cmake

diff --git a/cmake/FindSphinx.cmake b/cmake/FindSphinx.cmake
index 52a456c..d1488eb 100644
--- a/cmake/FindSphinx.cmake
+++ b/cmake/FindSphinx.cmake
@@ -29,41 +29,96 @@
 # Author: pablo.speciale@gmail.com (Pablo Speciale)
 #
 
-# Find the Sphinx documentation generator
-#
-# This modules defines
-#  SPHINX_EXECUTABLE
-#  SPHINX_FOUND
+#[=======================================================================[.rst:
+FindSphinx
+==========
 
-find_program(SPHINX_EXECUTABLE
-             NAMES sphinx-build
-             PATHS /opt/local/bin
-             DOC "Sphinx documentation generator")
+Module for locating Sphinx and its components.
 
-if (SPHINX_EXECUTABLE)
+This modules defines the following variables:
 
-  find_package(Python COMPONENTS Interpreter)
+``Sphinx_FOUND``
+  ``TRUE`` iff Sphinx and all of its components have been found.
 
-  if(Python_Interpreter_FOUND)
-    # Check for sphinx theme dependency for documentation
-    execute_process(
-      COMMAND ${Python_EXECUTABLE} -c "import sphinx_rtd_theme"
-      RESULT_VARIABLE SPHINX_RTD_THEME
-      OUTPUT_QUIET
-      ERROR_QUIET
-    )
-  endif ()
+``Sphinx_BUILD_EXECUTABLE``
+  Path to the ``sphinx-build`` tool.
+]=======================================================================]
 
-  if (SPHINX_RTD_THEME EQUAL 0)
-    set(SPHINX_RTD_THEME TRUE)
-  else ()
-    set(SPHINX_RTD_THEME FALSE)
-  endif ()
+include (FindPackageHandleStandardArgs)
 
-endif ()
+find_program (Sphinx_BUILD_EXECUTABLE
+  NAMES sphinx-build
+  PATHS /opt/local/bin
+  DOC "Sphinx documentation generator"
+)
 
-include(FindPackageHandleStandardArgs)
+mark_as_advanced (Sphinx_BUILD_EXECUTABLE)
 
-find_package_handle_standard_args(Sphinx DEFAULT_MSG SPHINX_EXECUTABLE SPHINX_RTD_THEME)
+if (Sphinx_BUILD_EXECUTABLE)
+  execute_process (
+    COMMAND ${Sphinx_BUILD_EXECUTABLE} --version
+    ERROR_STRIP_TRAILING_WHITESPACE
+    ERROR_VARIABLE _Sphinx_BUILD_ERROR
+    OUTPUT_STRIP_TRAILING_WHITESPACE
+    OUTPUT_VARIABLE _Sphinx_VERSION_STRING
+    RESULT_VARIABLE _Sphinx_BUILD_RESULT
+  )
 
-mark_as_advanced(SPHINX_EXECUTABLE)
+  if (_Sphinx_BUILD_RESULT EQUAL 0)
+    string (REGEX REPLACE "^sphinx-build[ \t]+([^ \t]+)$" "\\1" Sphinx_VERSION
+      "${_Sphinx_VERSION_STRING}")
+
+    if (Sphinx_VERSION MATCHES "[0-9]+\\.[0-9]+\\.[0-9]+")
+      set (Sphinx_VERSION_COMPONENTS 3)
+      set (Sphinx_VERSION_MAJOR ${CMAKE_MATCH_1})
+      set (Sphinx_VERSION_MINOR ${CMAKE_MATCH_2})
+      set (Sphinx_VERSION_PATCH ${CMAKE_MATCH_3})
+    endif (Sphinx_VERSION MATCHES "[0-9]+\\.[0-9]+\\.[0-9]+")
+  else (_Sphinx_BUILD_RESULT EQUAL 0)
+    message (WARNING "Could not determine sphinx-build version: ${_Sphinx_BUILD_ERROR}")
+  endif (_Sphinx_BUILD_RESULT EQUAL 0)
+
+  unset (_Sphinx_BUILD_ERROR)
+  unset (_Sphinx_BUILD_RESULT)
+  unset (_Sphinx_VERSION_STRING)
+
+  find_package (Python COMPONENTS Interpreter)
+  set (_Sphinx_BUILD_RESULT FALSE)
+
+  if (Python_Interpreter_FOUND)
+    # Check for Sphinx theme dependency for documentation
+    foreach (component IN LISTS Sphinx_FIND_COMPONENTS)
+      string (REGEX MATCH "^(.+_theme)$" theme_component "${component}")
+
+      if (NOT theme_component STREQUAL component)
+        continue ()
+      endif (NOT theme_component STREQUAL component)
+
+      execute_process (
+        COMMAND ${Python_EXECUTABLE} -c "import ${theme_component}"
+        ERROR_STRIP_TRAILING_WHITESPACE
+        ERROR_VARIABLE _Sphinx_BUILD_ERROR
+        OUTPUT_QUIET
+        RESULT_VARIABLE _Sphinx_BUILD_RESULT
+      )
+
+      if (_Sphinx_BUILD_RESULT EQUAL 0)
+        set (Sphinx_${component}_FOUND TRUE)
+      elseif (_Sphinx_BUILD_RESULT EQUAL 0)
+        message (WARNING "Could not determine whether Sphinx component '${theme_component}' is available: ${_Sphinx_BUILD_ERROR}")
+        set (Sphinx_${component}_FOUND FALSE)
+      endif (_Sphinx_BUILD_RESULT EQUAL 0)
+
+      unset (_Sphinx_BUILD_ERROR)
+      unset (_Sphinx_BUILD_RESULT)
+    endforeach (component)
+
+    unset (theme_component)
+  endif (Python_Interpreter_FOUND)
+endif (Sphinx_BUILD_EXECUTABLE)
+
+find_package_handle_standard_args (Sphinx
+  REQUIRED_VARS Sphinx_BUILD_EXECUTABLE
+  VERSION_VAR Sphinx_VERSION
+  HANDLE_COMPONENTS
+)

docs/source/CMakeLists.txt

diff --git a/docs/source/CMakeLists.txt b/docs/source/CMakeLists.txt
index 144316d..1f8fed8 100644
--- a/docs/source/CMakeLists.txt
+++ b/docs/source/CMakeLists.txt
@@ -1,5 +1,3 @@
-find_package(Sphinx REQUIRED)
-
 # HTML output directory
 set(SPHINX_HTML_DIR "${Ceres_BINARY_DIR}/docs/html")
 
@@ -18,6 +16,6 @@
                   "${Ceres_SOURCE_DIR}/scripts/make_docs.py"
                   "${Ceres_SOURCE_DIR}"
                   "${Ceres_BINARY_DIR}/docs"
-                  "${SPHINX_EXECUTABLE}"
+                  "${Sphinx_BUILD_EXECUTABLE}"
                   USES_TERMINAL
                   COMMENT "Building HTML documentation with Sphinx")