Add documentation generation using Sphinx

This is deliberately modelled very closely on CMake's documentation
system.  It's a hefty patch, because it involved changing all the
documentation to be in reStructuredText format.  I also cleaned up the
copyright/license statements at the same time.

Note that the find modules contain the full license, due to the fact
that ecm_use_find_module() copies them out of the ECM distribution.

34 files changed, 605 insertions, 0 deletions

diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt
new file mode 100644
index 00000000..ff04e7de
--- /dev/null
+++ b/docs/CMakeLists.txt
@@ -0,0 +1,125 @@
+#=============================================================================
+# CMake - Cross Platform Makefile Generator
+# Copyright 2000-2013 Kitware, Inc., Insight Software Consortium
+# Copyright 2014 Alex Merry <alex.merry@kde.org>
+#
+# Distributed under the OSI-approved BSD License (the "License");
+# see accompanying file Copyright.txt 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
+find_program(SPHINX_EXECUTABLE
+    NAMES
+        sphinx-build
+        sphinx-build2
+        sphinx-build3
+    DOC "Sphinx Documentation Builder (sphinx-doc.org)"
+)
+if(SPHINX_EXECUTABLE)
+    set(build_docs_default ON)
+else()
+    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)
+
+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()
+
+# 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)
+    list(APPEND doc_formats html)
+endif()
+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
+    )
+endif()
+
+
+set(doc_format_outputs "")
+set(doc_format_last "")
+foreach(format ${doc_formats})
+    set(doc_format_output "doc_format_${format}")
+    set(doc_format_log "build-${format}.log")
+    add_custom_command(
+        OUTPUT ${doc_format_output}
+        COMMAND
+            ${SPHINX_EXECUTABLE}
+            -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
+        DEPENDS ${doc_format_last}
+        COMMENT "sphinx-build ${format}: see ${CMAKE_CURRENT_BINARY_DIR}/${doc_format_log}"
+        VERBATIM
+    )
+    set_property(SOURCE ${doc_format_output} PROPERTY SYMBOLIC 1)
+    list(APPEND doc_format_outputs ${doc_format_output})
+    set(doc_format_last ${doc_format_output})
+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)
+    foreach(m ${man_rst})
+        if("x${m}" MATCHES "^x(.+)\\.([1-9])\\.rst$")
+            set(name "${CMAKE_MATCH_1}")
+            set(sec "${CMAKE_MATCH_2}")
+            install(
+                FILES ${CMAKE_CURRENT_BINARY_DIR}/man/${name}.${sec}
+                DESTINATION ${MAN_INSTALL_DIR}/man${sec}
+            )
+        endif()
+    endforeach()
+endif()
+if(BUILD_HTML_DOCS)
+    install(
+        DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/html
+        DESTINATION ${DOC_INSTALL_DIR}
+        PATTERN .buildinfo EXCLUDE
+        PATTERN objects.inv EXCLUDE
+    )
+endif()
+if(BUILD_QTHELP_DOCS)
+    install(
+        FILES ${CMAKE_CURRENT_BINARY_DIR}/qthelp/extra-cmake-modules.qch
+        DESTINATION ${DOC_INSTALL_DIR}
+    )
+endif()
diff --git a/docs/find-module/FindEGL.rst b/docs/find-module/FindEGL.rst
new file mode 100644
index 00000000..6eb9710c
--- /dev/null
+++ b/docs/find-module/FindEGL.rst
@@ -0,0 +1 @@
+.. ecm-module:: ../../find-modules/FindEGL.cmake
diff --git a/docs/find-module/FindOpenEXR.rst b/docs/find-module/FindOpenEXR.rst
new file mode 100644
index 00000000..abefc855
--- /dev/null
+++ b/docs/find-module/FindOpenEXR.rst
@@ -0,0 +1 @@
+.. ecm-module:: ../../find-modules/FindOpenEXR.cmake
diff --git a/docs/find-module/FindSharedMimeInfo.rst b/docs/find-module/FindSharedMimeInfo.rst
new file mode 100644
index 00000000..678eb516
--- /dev/null
+++ b/docs/find-module/FindSharedMimeInfo.rst
@@ -0,0 +1 @@
+.. ecm-module:: ../../find-modules/FindSharedMimeInfo.cmake
diff --git a/docs/find-module/FindWayland.rst b/docs/find-module/FindWayland.rst
new file mode 100644
index 00000000..c64c6d85
--- /dev/null
+++ b/docs/find-module/FindWayland.rst
@@ -0,0 +1 @@
+.. ecm-module:: ../../find-modules/FindWayland.cmake
diff --git a/docs/find-module/FindX11_XCB.rst b/docs/find-module/FindX11_XCB.rst
new file mode 100644
index 00000000..30b92464
--- /dev/null
+++ b/docs/find-module/FindX11_XCB.rst
@@ -0,0 +1 @@
+.. ecm-module:: ../../find-modules/FindX11_XCB.cmake
diff --git a/docs/find-module/FindXCB.rst b/docs/find-module/FindXCB.rst
new file mode 100644
index 00000000..31e22282
--- /dev/null
+++ b/docs/find-module/FindXCB.rst
@@ -0,0 +1 @@
+.. ecm-module:: ../../find-modules/FindXCB.cmake
diff --git a/docs/index.rst b/docs/index.rst
new file mode 100644
index 00000000..1441005f
--- /dev/null
+++ b/docs/index.rst
@@ -0,0 +1,19 @@
+.. title:: Extra CMake Modules Reference Documentation
+
+Reference Manuals
+#################
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   /manual/ecm.7
+   /manual/*
+
+.. only:: html
+
+ Index and Search
+ ################
+
+ * :ref:`genindex`
+ * :ref:`search`
diff --git a/docs/kde-module/KDECMakeSettings.rst b/docs/kde-module/KDECMakeSettings.rst
new file mode 100644
index 00000000..48ab140e
--- /dev/null
+++ b/docs/kde-module/KDECMakeSettings.rst
@@ -0,0 +1 @@
+.. ecm-module:: ../../kde-modules/KDECMakeSettings.cmake
diff --git a/docs/kde-module/KDECompilerSettings.rst b/docs/kde-module/KDECompilerSettings.rst
new file mode 100644
index 00000000..28f3e9c5
--- /dev/null
+++ b/docs/kde-module/KDECompilerSettings.rst
@@ -0,0 +1 @@
+.. ecm-module:: ../../kde-modules/KDECompilerSettings.cmake
diff --git a/docs/kde-module/KDEFrameworkCompilerSettings.rst b/docs/kde-module/KDEFrameworkCompilerSettings.rst
new file mode 100644
index 00000000..6b8d7df5
--- /dev/null
+++ b/docs/kde-module/KDEFrameworkCompilerSettings.rst
@@ -0,0 +1 @@
+.. ecm-module:: ../../kde-modules/KDEFrameworkCompilerSettings.cmake
diff --git a/docs/kde-module/KDEInstallDirs.rst b/docs/kde-module/KDEInstallDirs.rst
new file mode 100644
index 00000000..06435172
--- /dev/null
+++ b/docs/kde-module/KDEInstallDirs.rst
@@ -0,0 +1 @@
+.. ecm-module:: ../../kde-modules/KDEInstallDirs.cmake
diff --git a/docs/manual/ecm-find-modules.7.rst b/docs/manual/ecm-find-modules.7.rst
new file mode 100644
index 00000000..4e3fc984
--- /dev/null
+++ b/docs/manual/ecm-find-modules.7.rst
@@ -0,0 +1,18 @@
+.. ecm-manual-description: ECM Find Modules Reference
+
+ecm-find-modules(7)
+*******************
+
+.. only:: html or latex
+
+   .. contents::
+
+All Find Modules
+================
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   /find-module/*
+
diff --git a/docs/manual/ecm-kde-modules.7.rst b/docs/manual/ecm-kde-modules.7.rst
new file mode 100644
index 00000000..b3dffd77
--- /dev/null
+++ b/docs/manual/ecm-kde-modules.7.rst
@@ -0,0 +1,18 @@
+.. ecm-manual-description: ECM KDE Modules Reference
+
+ecm-kde-modules(7)
+******************
+
+.. only:: html or latex
+
+   .. contents::
+
+All KDE Modules
+===============
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   /kde-module/*
+
diff --git a/docs/manual/ecm-modules.7.rst b/docs/manual/ecm-modules.7.rst
new file mode 100644
index 00000000..70b09f5e
--- /dev/null
+++ b/docs/manual/ecm-modules.7.rst
@@ -0,0 +1,18 @@
+.. ecm-manual-description: ECM Modules Reference
+
+ecm-modules(7)
+**************
+
+.. only:: html or latex
+
+   .. contents::
+
+All Modules
+===========
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   /module/*
+
diff --git a/docs/manual/ecm.7.rst b/docs/manual/ecm.7.rst
new file mode 100644
index 00000000..fdc444a6
--- /dev/null
+++ b/docs/manual/ecm.7.rst
@@ -0,0 +1,11 @@
+.. ecm-manual-description: Extra CMake Modules
+
+ecm(7)
+******
+
+.. only:: html or latex
+
+   .. contents::
+
+.. include:: ../../README.rst
+  :start-line: 2
diff --git a/docs/module/ECMAddTests.rst b/docs/module/ECMAddTests.rst
new file mode 100644
index 00000000..f971953a
--- /dev/null
+++ b/docs/module/ECMAddTests.rst
@@ -0,0 +1 @@
+.. ecm-module:: ../../modules/ECMAddTests.cmake
diff --git a/docs/module/ECMCreateQmFromPoFiles.rst b/docs/module/ECMCreateQmFromPoFiles.rst
new file mode 100644
index 00000000..13340c0a
--- /dev/null
+++ b/docs/module/ECMCreateQmFromPoFiles.rst
@@ -0,0 +1 @@
+.. ecm-module:: ../../modules/ECMCreateQmFromPoFiles.cmake
diff --git a/docs/module/ECMDBusAddActivationService.rst b/docs/module/ECMDBusAddActivationService.rst
new file mode 100644
index 00000000..2052faeb
--- /dev/null
+++ b/docs/module/ECMDBusAddActivationService.rst
@@ -0,0 +1 @@
+.. ecm-module:: ../../modules/ECMDBusAddActivationService.cmake
diff --git a/docs/module/ECMFindModuleHelpers.rst b/docs/module/ECMFindModuleHelpers.rst
new file mode 100644
index 00000000..bec8f822
--- /dev/null
+++ b/docs/module/ECMFindModuleHelpers.rst
@@ -0,0 +1 @@
+.. ecm-module:: ../../modules/ECMFindModuleHelpers.cmake
diff --git a/docs/module/ECMGenerateHeaders.rst b/docs/module/ECMGenerateHeaders.rst
new file mode 100644
index 00000000..ad3e4819
--- /dev/null
+++ b/docs/module/ECMGenerateHeaders.rst
@@ -0,0 +1 @@
+.. ecm-module:: ../../modules/ECMGenerateHeaders.cmake
diff --git a/docs/module/ECMGeneratePriFile.rst b/docs/module/ECMGeneratePriFile.rst
new file mode 100644
index 00000000..1cb4d6a4
--- /dev/null
+++ b/docs/module/ECMGeneratePriFile.rst
@@ -0,0 +1 @@
+.. ecm-module:: ../../modules/ECMGeneratePriFile.cmake
diff --git a/docs/module/ECMInstallIcons.rst b/docs/module/ECMInstallIcons.rst
new file mode 100644
index 00000000..7bb70ea5
--- /dev/null
+++ b/docs/module/ECMInstallIcons.rst
@@ -0,0 +1 @@
+.. ecm-module:: ../../modules/ECMInstallIcons.cmake
diff --git a/docs/module/ECMMarkAsTest.rst b/docs/module/ECMMarkAsTest.rst
new file mode 100644
index 00000000..8b6a8752
--- /dev/null
+++ b/docs/module/ECMMarkAsTest.rst
@@ -0,0 +1 @@
+.. ecm-module:: ../../modules/ECMMarkAsTest.cmake
diff --git a/docs/module/ECMMarkNonGuiExecutable.rst b/docs/module/ECMMarkNonGuiExecutable.rst
new file mode 100644
index 00000000..2684fee6
--- /dev/null
+++ b/docs/module/ECMMarkNonGuiExecutable.rst
@@ -0,0 +1 @@
+.. ecm-module:: ../../modules/ECMMarkNonGuiExecutable.cmake
diff --git a/docs/module/ECMOptionalAddSubdirectory.rst b/docs/module/ECMOptionalAddSubdirectory.rst
new file mode 100644
index 00000000..af9595ec
--- /dev/null
+++ b/docs/module/ECMOptionalAddSubdirectory.rst
@@ -0,0 +1 @@
+.. ecm-module:: ../../modules/ECMOptionalAddSubdirectory.cmake
diff --git a/docs/module/ECMPackageConfigHelpers.rst b/docs/module/ECMPackageConfigHelpers.rst
new file mode 100644
index 00000000..21102c4f
--- /dev/null
+++ b/docs/module/ECMPackageConfigHelpers.rst
@@ -0,0 +1 @@
+.. ecm-module:: ../../modules/ECMPackageConfigHelpers.cmake
diff --git a/docs/module/ECMSetupVersion.rst b/docs/module/ECMSetupVersion.rst
new file mode 100644
index 00000000..f984a81f
--- /dev/null
+++ b/docs/module/ECMSetupVersion.rst
@@ -0,0 +1 @@
+.. ecm-module:: ../../modules/ECMSetupVersion.cmake
diff --git a/docs/module/ECMUseFindModules.rst b/docs/module/ECMUseFindModules.rst
new file mode 100644
index 00000000..48bbf35a
--- /dev/null
+++ b/docs/module/ECMUseFindModules.rst
@@ -0,0 +1 @@
+.. ecm-module:: ../../modules/ECMUseFindModules.cmake
diff --git a/docs/sphinx/.gitignore b/docs/sphinx/.gitignore
new file mode 100644
index 00000000..0d20b648
--- /dev/null
+++ b/docs/sphinx/.gitignore
@@ -0,0 +1 @@
+*.pyc
diff --git a/docs/sphinx/conf.py.in b/docs/sphinx/conf.py.in
new file mode 100644
index 00000000..24ba82c8
--- /dev/null
+++ b/docs/sphinx/conf.py.in
@@ -0,0 +1,63 @@
+#=============================================================================
+# CMake - Cross Platform Makefile Generator
+# Copyright 2000-2013 Kitware, Inc., Insight Software Consortium
+#
+# Distributed under the OSI-approved BSD License (the "License");
+# see accompanying file Copyright.txt 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.
+#=============================================================================
+import sys
+import os
+import re
+import glob
+
+sys.path.insert(0, r'@conf_path@')
+
+source_suffix = '.rst'
+master_doc = 'index'
+
+project = 'Extra CMake Modules'
+copyright = 'KDE Developers'
+version = '@conf_version@' # feature version
+release = '@conf_release@' # 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_manual_description = re.compile('^\.\. ecm-manual-description:(.*)$')
+man_pages = []
+for fpath in ecm_manuals:
+    try:
+        name, sec, rst = os.path.basename(fpath).split('.')
+        desc = None
+        f = open(fpath, 'r')
+        for l in f:
+            m = ecm_manual_description.match(l)
+            if m:
+                desc = m.group(1).strip()
+                break
+        f.close()
+        if desc:
+            man_pages.append(('manual/%s.%s' % (name, sec),
+                              name, desc, [], int(sec)))
+        else:
+            sys.stderr.write("ERROR: No ecm-manual-description in '%s'\n" % fpath)
+    except Exception, e:
+        sys.stderr.write("ERROR: %s\n" % str(e))
+man_show_urls = False
+
+html_show_sourcelink = True
+html_static_path = ['@conf_path@/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'
diff --git a/docs/sphinx/ecm.py b/docs/sphinx/ecm.py
new file mode 100644
index 00000000..9b76e1a9
--- /dev/null
+++ b/docs/sphinx/ecm.py
@@ -0,0 +1,301 @@
+# Copyright 2014 Alex Merry <alex.merry@kde.org>
+# Based on cmake.py from CMake:
+# Copyright 2000-2013 Kitware, Inc., Insight Software Consortium
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions
+# are met:
+#
+# 1. Redistributions of source code must retain the copyright
+#    notice, this list of conditions and the following disclaimer.
+# 2. Redistributions in binary form must reproduce the copyright
+#    notice, this list of conditions and the following disclaimer in the
+#    documentation and/or other materials provided with the distribution.
+# 3. The name of the author may not be used to endorse or promote products
+#    derived from this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+# IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+# OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+# IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+# INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+# NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+# THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+import os
+import re
+
+# Monkey patch for pygments reporting an error when generator expressions are
+# used.
+# https://bitbucket.org/birkenfeld/pygments-main/issue/942/cmake-generator-expressions-not-handled
+from pygments.lexers import CMakeLexer
+from pygments.token import Name, Operator
+from pygments.lexer import bygroups
+CMakeLexer.tokens["args"].append(('(\\$<)(.+?)(>)',
+                                  bygroups(Operator, Name.Variable, Operator)))
+
+# Monkey patch for sphinx generating invalid content for qcollectiongenerator
+# https://bitbucket.org/birkenfeld/sphinx/issue/1435/qthelp-builder-should-htmlescape-keywords
+from sphinx.util.pycompat import htmlescape
+from sphinx.builders.qthelp import QtHelpBuilder
+old_build_keywords = QtHelpBuilder.build_keywords
+def new_build_keywords(self, title, refs, subitems):
+  old_items = old_build_keywords(self, title, refs, subitems)
+  new_items = []
+  for item in old_items:
+    before, rest = item.split("ref=\"", 1)
+    ref, after = rest.split("\"")
+    if ("<" in ref and ">" in ref):
+      new_items.append(before + "ref=\"" + htmlescape(ref) + "\"" + after)
+    else:
+      new_items.append(item)
+  return new_items
+QtHelpBuilder.build_keywords = new_build_keywords
+
+
+from docutils.parsers.rst import Directive, directives
+from docutils.transforms import Transform
+try:
+    from docutils.utils.error_reporting import SafeString, ErrorString
+except ImportError:
+    # error_reporting was not in utils before version 0.11:
+    from docutils.error_reporting import SafeString, ErrorString
+
+from docutils import io, nodes
+
+from sphinx.directives import ObjectDescription
+from sphinx.domains import Domain, ObjType
+from sphinx.roles import XRefRole
+from sphinx.util.nodes import make_refnode
+from sphinx import addnodes
+
+class ECMModule(Directive):
+    required_arguments = 1
+    optional_arguments = 0
+    final_argument_whitespace = True
+    option_spec = {'encoding': directives.encoding}
+
+    def __init__(self, *args, **keys):
+        self.re_start = re.compile(r'^#\[(?P<eq>=*)\[\.rst:$')
+        Directive.__init__(self, *args, **keys)
+
+    def run(self):
+        settings = self.state.document.settings
+        if not settings.file_insertion_enabled:
+            raise self.warning('"%s" directive disabled.' % self.name)
+
+        env = self.state.document.settings.env
+        rel_path, path = env.relfn2path(self.arguments[0])
+        path = os.path.normpath(path)
+        encoding = self.options.get('encoding', settings.input_encoding)
+        e_handler = settings.input_encoding_error_handler
+        try:
+            settings.record_dependencies.add(path)
+            f = io.FileInput(source_path=path, encoding=encoding,
+                             error_handler=e_handler)
+        except UnicodeEncodeError, error:
+            raise self.severe('Problems with "%s" directive path:\n'
+                              'Cannot encode input file path "%s" '
+                              '(wrong locale?).' %
+                              (self.name, SafeString(path)))
+        except IOError, error:
+            raise self.severe('Problems with "%s" directive path:\n%s.' %
+                      (self.name, ErrorString(error)))
+        raw_lines = f.read().splitlines()
+        f.close()
+        rst = None
+        lines = []
+        for line in raw_lines:
+            if rst is not None and rst != '#':
+                # Bracket mode: check for end bracket
+                pos = line.find(rst)
+                if pos >= 0:
+                    if line[0] == '#':
+                        line = ''
+                    else:
+                        line = line[0:pos]
+                    rst = None
+            else:
+                # Line mode: check for .rst start (bracket or line)
+                m = self.re_start.match(line)
+                if m:
+                    rst = ']%s]' % m.group('eq')
+                    line = ''
+                elif line == '#.rst:':
+                    rst = '#'
+                    line = ''
+                elif rst == '#':
+                    if line == '#' or line[:2] == '# ':
+                        line = line[2:]
+                    else:
+                        rst = None
+                        line = ''
+                elif rst is None:
+                    line = ''
+            lines.append(line)
+        if rst is not None and rst != '#':
+            raise self.warning('"%s" found unclosed bracket "#[%s[.rst:" in %s' %
+                               (self.name, rst[1:-1], path))
+        self.state_machine.insert_input(lines, path)
+        return []
+
+class _ecm_index_entry:
+    def __init__(self, desc):
+        self.desc = desc
+
+    def __call__(self, title, targetid):
+        return ('pair', u'%s ; %s' % (self.desc, title), targetid, 'main')
+
+_ecm_index_objs = {
+    'manual':      _ecm_index_entry('manual'),
+    'module':      _ecm_index_entry('module'),
+    'find-module': _ecm_index_entry('find-module'),
+    'kde-module':  _ecm_index_entry('kde-module'),
+    }
+
+def _ecm_object_inventory(env, document, line, objtype, targetid):
+    inv = env.domaindata['ecm']['objects']
+    if targetid in inv:
+        document.reporter.warning(
+            'ECM object "%s" also described in "%s".' %
+            (targetid, env.doc2path(inv[targetid][0])), line=line)
+    inv[targetid] = (env.docname, objtype)
+
+class ECMTransform(Transform):
+
+    # Run this transform early since we insert nodes we want
+    # treated as if they were written in the documents.
+    default_priority = 210
+
+    def __init__(self, document, startnode):
+        Transform.__init__(self, document, startnode)
+        self.titles = {}
+
+    def parse_title(self, docname):
+        """Parse a document title as the first line starting in [A-Za-z0-9<]
+           or fall back to the document basename if no such line exists.
+           Return the title or False if the document file does not exist.
+        """
+        env = self.document.settings.env
+        title = self.titles.get(docname)
+        if title is None:
+            fname = os.path.join(env.srcdir, docname+'.rst')
+            try:
+                f = open(fname, 'r')
+            except IOError:
+                title = False
+            else:
+                for line in f:
+                    if len(line) > 0 and (line[0].isalnum() or line[0] == '<'):
+                        title = line.rstrip()
+                        break
+                f.close()
+                if title is None:
+                    title = os.path.basename(docname)
+            self.titles[docname] = title
+        return title
+
+    def apply(self):
+        env = self.document.settings.env
+
+        # Treat some documents as ecm domain objects.
+        objtype, sep, tail = env.docname.rpartition('/')
+        make_index_entry = _ecm_index_objs.get(objtype)
+        if make_index_entry:
+            title = self.parse_title(env.docname)
+            # Insert the object link target.
+            targetid = '%s:%s' % (objtype, title)
+            targetnode = nodes.target('', '', ids=[targetid])
+            self.document.insert(0, targetnode)
+            # Insert the object index entry.
+            indexnode = addnodes.index()
+            indexnode['entries'] = [make_index_entry(title, targetid)]
+            self.document.insert(0, indexnode)
+            # Add to ecm domain object inventory
+            _ecm_object_inventory(env, self.document, 1, objtype, targetid)
+
+class ECMObject(ObjectDescription):
+
+    def handle_signature(self, sig, signode):
+        # called from sphinx.directives.ObjectDescription.run()
+        signode += addnodes.desc_name(sig, sig)
+        return sig
+
+    def add_target_and_index(self, name, sig, signode):
+        targetid = '%s:%s' % (self.objtype, name)
+        if targetid not in self.state.document.ids:
+            signode['names'].append(targetid)
+            signode['ids'].append(targetid)
+            signode['first'] = (not self.names)
+            self.state.document.note_explicit_target(signode)
+            _ecm_object_inventory(self.env, self.state.document,
+                                    self.lineno, self.objtype, targetid)
+
+        make_index_entry = _ecm_index_objs.get(self.objtype)
+        if make_index_entry:
+            self.indexnode['entries'].append(make_index_entry(name, targetid))
+
+class ECMXRefRole(XRefRole):
+
+    # See sphinx.util.nodes.explicit_title_re; \x00 escapes '<'.
+    _re = re.compile(r'^(.+?)(\s*)(?<!\x00)<(.*?)>$', re.DOTALL)
+    _re_sub = re.compile(r'^([^()\s]+)\s*\(([^()]*)\)$', re.DOTALL)
+
+    def __call__(self, typ, rawtext, text, *args, **keys):
+        # CMake cross-reference targets may contain '<' so escape
+        # any explicit `<target>` with '<' not preceded by whitespace.
+        while True:
+            m = ECMXRefRole._re.match(text)
+            if m and len(m.group(2)) == 0:
+                text = '%s\x00<%s>' % (m.group(1), m.group(3))
+            else:
+                break
+        return XRefRole.__call__(self, typ, rawtext, text, *args, **keys)
+
+class ECMDomain(Domain):
+    """ECM domain."""
+    name = 'ecm'
+    label = 'ECM'
+    object_types = {
+        'module':      ObjType('module',      'module'),
+        'kde-module':  ObjType('kde-module',  'kde-module'),
+        'find-module': ObjType('find-module', 'find-module'),
+        'manual':      ObjType('manual',      'manual'),
+    }
+    directives = {}
+    roles = {
+        'module':      XRefRole(),
+        'kde-module':  XRefRole(),
+        'find-module': XRefRole(),
+        'manual':      XRefRole(),
+    }
+    initial_data = {
+        'objects': {},  # fullname -> docname, objtype
+    }
+
+    def clear_doc(self, docname):
+        for fullname, (fn, _) in self.data['objects'].items():
+            if fn == docname:
+                del self.data['objects'][fullname]
+
+    def resolve_xref(self, env, fromdocname, builder,
+                     typ, target, node, contnode):
+        targetid = '%s:%s' % (typ, target)
+        obj = self.data['objects'].get(targetid)
+        if obj is None:
+            # TODO: warn somehow?
+            return None
+        return make_refnode(builder, fromdocname, obj[0], targetid,
+                            contnode, target)
+
+    def get_objects(self):
+        for refname, (docname, type) in self.data['objects'].iteritems():
+            yield (refname, refname, type, docname, refname, 1)
+
+def setup(app):
+    app.add_directive('ecm-module', ECMModule)
+    app.add_transform(ECMTransform)
+    app.add_domain(ECMDomain)
diff --git a/docs/sphinx/kde-favicon.ico b/docs/sphinx/kde-favicon.ico
new file mode 100644
index 00000000..3741beba
--- /dev/null
+++ b/docs/sphinx/kde-favicon.ico
diff --git a/docs/sphinx/static/ecm.css b/docs/sphinx/static/ecm.css
new file mode 100644
index 00000000..2a326d47
--- /dev/null
+++ b/docs/sphinx/static/ecm.css
@@ -0,0 +1,8 @@
+/* Import the Sphinx theme style.  */
+@import url("default.css");
+
+/* Wrap sidebar content even within words so that long
+   document names do not escape sidebar borders.  */
+div.sphinxsidebarwrapper {
+  word-wrap: break-word;
+}