Overhaul the ECM build system.

It should now be easier to read, and more featureful. Among other
tweaks, we now print a summary of dependencies and build options, and
the documentation is generated with more sensible breadcrumbs and
builds properly with Sphinx 1.3.

REVIEW: 126075

4 files changed, 67 insertions, 60 deletions

diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt
index f17400f8..1f307855 100644
--- a/docs/CMakeLists.txt
+++ b/docs/CMakeLists.txt
@@ -1,51 +1,55 @@
 #=============================================================================
-# CMake - Cross Platform Makefile Generator
-# Copyright 2000-2013 Kitware, Inc., Insight Software Consortium
-# Copyright 2014 Alex Merry <alex.merry@kde.org>
+# Copyright 2000-2013 Kitware, Inc.
+# Copyright 2014-2015 Alex Merry <alex.merry@kde.org>
 #
 # Distributed under the OSI-approved BSD License (the "License");
-# see accompanying file Copyright.txt for details.
+# see accompanying file COPYING-CMAKE-SCRIPTS for details.
 #
 # This software is distributed WITHOUT ANY WARRANTY; without even the
 # implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 # See the License for more information.
 #=============================================================================
 
-# Distros sometimes rename Python executables to allow for parallel
-# installation of Python2 and Python3 versions
-message(STATUS "Looking for Sphinx Documentation Builder...")
-find_program(SPHINX_EXECUTABLE
-    NAMES
-        sphinx-build
-        sphinx-build2
-        sphinx-build3
-    DOC "Sphinx Documentation Builder (http://sphinx-doc.org/)"
+include(CMakeDependentOption)
+
+find_package(Sphinx 1.2 MODULE)
+set_package_properties(
+    Sphinx
+    PROPERTIES
+        URL "http://sphinx-doc.org/"
+        DESCRIPTION "Tool to generate documentation."
+        TYPE OPTIONAL
+        PURPOSE "Required to build documentation for Extra CMake Modules."
 )
-if(SPHINX_EXECUTABLE)
-    message(STATUS "Sphinx Documentation Builder found at ${SPHINX_EXECUTABLE} - building documentation")
-    set(build_docs_default ON)
-else()
-    message(STATUS "Sphinx Documentation Builder not found - documentation will not be built (see http://sphinx-doc.org/)")
-    set(build_docs_default OFF)
-endif()
 
-option(BUILD_HTML_DOCS "Build html help with Sphinx" ${build_docs_default})
-option(BUILD_MAN_DOCS "Build man pages with Sphinx" ${build_docs_default})
-option(BUILD_QTHELP_DOCS "Build Qt help with Sphinx" OFF)
+find_package(QCollectionGenerator MODULE)
+set_package_properties(
+    QCollectionGenerator
+    PROPERTIES
+        URL "http://www.qt.io/"
+        DESCRIPTION "Qt help collection generator."
+        TYPE OPTIONAL
+        PURPOSE "Required to build Extra CMake Modules documentation in Qt Help format."
+)
 
-if(NOT BUILD_HTML_DOCS AND NOT BUILD_MAN_DOCS AND NOT BUILD_QTHELP_DOCS)
-    return()
-elseif(NOT SPHINX_EXECUTABLE)
-    message(FATAL_ERROR "SPHINX_EXECUTABLE (sphinx-build) was not found!")
-endif()
+cmake_dependent_option(
+    BUILD_HTML_DOCS "Build html help with Sphinx" ON
+    "Sphinx_FOUND" OFF
+)
+add_feature_info(BUILD_HTML_DOCS BUILD_HTML_DOCS "Generate HTML documentation for installed modules.")
+
+cmake_dependent_option(
+    BUILD_MAN_DOCS "Build man pages with Sphinx" ON
+    "Sphinx_FOUND" OFF
+)
+add_feature_info(BUILD_MAN_DOCS BUILD_MAN_DOCS "Generate man page documentation for installed modules.")
+
+cmake_dependent_option(
+    BUILD_QTHELP_DOCS "Build Qt help with Sphinx" OFF
+    "Sphinx_FOUND;QCollectionGenerator_FOUND" OFF
+)
+add_feature_info(BUILD_QTHELP_DOCS BUILD_QTHELP_DOCS "Generate QtHelp documentation for installed modules.")
 
-# the docs/ directory
-set(conf_docs "${CMAKE_CURRENT_SOURCE_DIR}")
-# where cmake.py and other sphinx files are
-set(conf_path "${CMAKE_CURRENT_SOURCE_DIR}/sphinx")
-set(conf_version "${extra-cmake-modules_VERSION_MAJOR}.${extra-cmake-modules_VERSION_MINOR}.${extra-cmake-modules_VERSION_PATCH}")
-set(conf_release "${extra-cmake-modules_VERSION}")
-configure_file(sphinx/conf.py.in conf.py @ONLY)
 
 set(doc_formats "")
 if(BUILD_HTML_DOCS)
@@ -55,22 +59,26 @@ if(BUILD_MAN_DOCS)
     list(APPEND doc_formats man)
 endif()
 if(BUILD_QTHELP_DOCS)
-    find_program(QCOLLECTIONGENERATOR_EXECUTABLE
-        NAMES qcollectiongenerator
-        DOC "qcollectiongenerator tool"
-    )
-    if (NOT QCOLLECTIONGENERATOR_EXECUTABLE)
-        message(FATAL_ERROR "QCOLLECTIONGENERATOR_EXECUTABLE (qcollectiongenerator) not found!")
-    endif()
     list(APPEND doc_formats qthelp)
-
     set(qthelp_extra_commands
         COMMAND
-            qcollectiongenerator
-            ${CMAKE_CURRENT_BINARY_DIR}/qthelp/extra-cmake-modules.qhcp
+            QCollectionGenerator::Generator
+            ${CMAKE_CURRENT_BINARY_DIR}/qthelp/ExtraCMakeModules.qhcp
     )
 endif()
 
+if(NOT doc_formats)
+    return()
+endif()
+
+if (Sphinx_VERSION VERSION_LESS 1.3)
+    set(sphinx_theme default)
+else()
+    set(sphinx_theme classic)
+endif()
+configure_file(sphinx/conf.py.in conf.py @ONLY)
+configure_file(sphinx/ecm.css.in static/ecm.css)
+
 
 set(doc_format_outputs "")
 set(doc_format_last "")
@@ -80,13 +88,14 @@ foreach(format ${doc_formats})
     add_custom_command(
         OUTPUT ${doc_format_output}
         COMMAND
-            ${SPHINX_EXECUTABLE}
+            Sphinx::Build
             -c ${CMAKE_CURRENT_BINARY_DIR}
             -d ${CMAKE_CURRENT_BINARY_DIR}/doctrees
             -b ${format}
             ${CMAKE_CURRENT_SOURCE_DIR}
             ${CMAKE_CURRENT_BINARY_DIR}/${format}
             > ${doc_format_log} # log stdout, pass stderr
+        ${${format}_extra_commands}
         DEPENDS ${doc_format_last}
         COMMENT "sphinx-build ${format}: see ${CMAKE_CURRENT_BINARY_DIR}/${doc_format_log}"
         VERBATIM
@@ -99,8 +108,8 @@ endforeach()
 add_custom_target(documentation ALL DEPENDS ${doc_format_outputs})
 
 if(BUILD_MAN_DOCS)
-    file(GLOB man_rst RELATIVE ${extra-cmake-modules_SOURCE_DIR}/docs/manual
-    ${extra-cmake-modules_SOURCE_DIR}/docs/manual/*.[1-9].rst)
+    file(GLOB man_rst RELATIVE ${ECM_SOURCE_DIR}/docs/manual
+        ${ECM_SOURCE_DIR}/docs/manual/*.[1-9].rst)
     foreach(m ${man_rst})
         if("x${m}" MATCHES "^x(.+)\\.([1-9])\\.rst$")
             set(name "${CMAKE_MATCH_1}")
@@ -122,7 +131,7 @@ if(BUILD_HTML_DOCS)
 endif()
 if(BUILD_QTHELP_DOCS)
     install(
-        FILES ${CMAKE_CURRENT_BINARY_DIR}/qthelp/extra-cmake-modules.qch
+        FILES ${CMAKE_CURRENT_BINARY_DIR}/qthelp/ExtraCMakeModules.qch
         DESTINATION ${DOC_INSTALL_DIR}
     )
 endif()
diff --git a/docs/sphinx/conf.py.in b/docs/sphinx/conf.py.in
index 792c87ca..d32b53f4 100644
--- a/docs/sphinx/conf.py.in
+++ b/docs/sphinx/conf.py.in
@@ -14,24 +14,23 @@ import os
 import re
 import glob
 
-sys.path.insert(0, r'@conf_path@')
+sys.path.insert(0, r'@CMAKE_CURRENT_SOURCE_DIR@/sphinx/ext')
 
 source_suffix = '.rst'
 master_doc = 'index'
 
 project = 'Extra CMake Modules'
 copyright = 'KDE Developers'
-version = '@conf_version@' # feature version
-release = '@conf_release@' # full version string
+version = '@PROJECT_VERSION_MAJOR@.@PROJECT_VERSION_MINOR@' # feature version
+release = '@PROJECT_VERSION@' # full version string
 
 primary_domain = 'ecm'
 
 exclude_patterns = []
 
 extensions = ['ecm']
-templates_path = ['@conf_path@/templates']
 
-ecm_manuals = sorted(glob.glob(r'@conf_docs@/manual/*.rst'))
+ecm_manuals = sorted(glob.glob(r'@CMAKE_CURRENT_SOURCE_DIR@/manual/*.rst'))
 ecm_manual_description = re.compile('^\.\. ecm-manual-description:(.*)$')
 man_pages = []
 for fpath in ecm_manuals:
@@ -55,9 +54,8 @@ for fpath in ecm_manuals:
 man_show_urls = False
 
 html_show_sourcelink = True
-html_static_path = ['@conf_path@/static']
+html_static_path = ['@CMAKE_CURRENT_BINARY_DIR@/static']
 html_style = 'ecm.css'
-html_theme = 'default'
-html_title = 'Extra CMake Modules %s Documentation' % release
-html_short_title = '%s Documentation' % release
-html_favicon = '@conf_path@/kde-favicon.ico'
+html_theme = '@sphinx_theme@'
+html_short_title = 'ECM %s documentation' % version
+html_favicon = '@CMAKE_CURRENT_SOURCE_DIR@/sphinx/kde-favicon.ico'
diff --git a/docs/sphinx/static/ecm.css b/docs/sphinx/ecm.css.in
index 2a326d47..a05e4527 100644
--- a/docs/sphinx/static/ecm.css
+++ b/docs/sphinx/ecm.css.in
@@ -1,5 +1,5 @@
 /* Import the Sphinx theme style.  */
-@import url("default.css");
+@import url("${sphinx_theme}.css");
 
 /* Wrap sidebar content even within words so that long
    document names do not escape sidebar borders.  */
diff --git a/docs/sphinx/ecm.py b/docs/sphinx/ext/ecm.py
index ed966bfb..ed966bfb 100644
--- a/docs/sphinx/ecm.py
+++ b/docs/sphinx/ext/ecm.py