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.

6 files changed, 236 insertions, 85 deletions

diff --git a/find-modules/FindEGL.cmake b/find-modules/FindEGL.cmake
index 6237f5cb..765b6692 100644
--- a/find-modules/FindEGL.cmake
+++ b/find-modules/FindEGL.cmake
@@ -1,20 +1,55 @@
-# Try to find EGL on a Unix system
+#.rst:
+# FindEGL
+# -------
 #
-# This will define:
+# Try to find EGL on a Unix system.
 #
-#   EGL_FOUND        - True if EGL is available
-#   EGL_LIBRARIES    - Link these to use EGL
-#   EGL_INCLUDE_DIRS - Include directory for EGL
-#   EGL_DEFINITIONS  - Compiler flags for using EGL
+# This will define the following variables:
 #
-# Additionally, the following imported targets will be defined:
+# ``EGL_FOUND``
+#     True if EGL is available
+# ``EGL_LIBRARIES``
+#     Link these to use EGL
+# ``EGL_INCLUDE_DIRS``
+#     Include directory for EGL
+# ``EGL_DEFINITIONS``
+#     Compiler flags for using EGL
 #
-#   EGL::EGL
+# and the following imported targets:
 #
-# Copyright (c) 2014 Martin Gräßlin <mgraesslin@kde.org>
+# ``EGL::EGL``
+#     The EGL library
 #
-# Redistribution and use is allowed according to the terms of the BSD license.
-# For details see the accompanying COPYING-CMAKE-SCRIPTS file.
+# In general we recommend using the imported target, as it is easier to use.
+# Bear in mind, however, that if the target is in the link interface of an
+# exported library, it must be made available by the package config file.
+
+#=============================================================================
+# Copyright 2014 Martin Gräßlin <mgraesslin@kde.org>
+#
+# 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.
+#=============================================================================
 
 if(CMAKE_VERSION VERSION_LESS 2.8.12)
     message(FATAL_ERROR "CMake 2.8.12 is required by FindEGL.cmake")
diff --git a/find-modules/FindOpenEXR.cmake b/find-modules/FindOpenEXR.cmake
index 00a2364e..85afebdf 100644
--- a/find-modules/FindOpenEXR.cmake
+++ b/find-modules/FindOpenEXR.cmake
@@ -1,17 +1,32 @@
-# Try to find the OpenEXR libraries
+#.rst:
+# FindOpenEXR
+# -----------
 #
-# This will define:
+# Try to find the OpenEXR libraries.
 #
-#   OpenEXR_FOUND        - True if OpenEXR is available
-#   OpenEXR_LIBRARIES    - Link to these to use OpenEXR
-#   OpenEXR_INCLUDE_DIRS - Include directory for OpenEXR
-#   OpenEXR_DEFINITIONS  - Compiler flags required to link against OpenEXR
-#   OpenEXR::IlmImf      - imported target to link against (instead of using the above variables)
+# This will define the following variables:
 #
+# ``OpenEXR_FOUND``
+#     True if OpenEXR is available
+# ``OpenEXR_LIBRARIES``
+#     Link to these to use OpenEXR
+# ``OpenEXR_INCLUDE_DIRS``
+#     Include directory for OpenEXR
+# ``OpenEXR_DEFINITIONS``
+#     Compiler flags required to link against OpenEXR
+#
+# and the following imported targets:
+#
+# ``OpenEXR::IlmImf``
+#     The OpenEXR core library
+#
+# In general we recommend using the imported target, as it is easier to use.
+# Bear in mind, however, that if the target is in the link interface of an
+# exported library, it must be made available by the package config file.
 
-
-# Copyright (c) 2006, Alexander Neundorf, <neundorf@kde.org>
-# Copyright (c) 2013-2014, Alex Merry, <alex.merry@kdemail.net>
+#=============================================================================
+# Copyright 2013-2014 Alex Merry <alex.merry@kdemail.net>
+# Copyright 2006 Alexander Neundorf <neundorf@kde.org>
 #
 # Redistribution and use in source and binary forms, with or without
 # modification, are permitted provided that the following conditions
@@ -35,6 +50,7 @@
 # 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.
+#=============================================================================
 
 
 if(${CMAKE_VERSION} VERSION_LESS 2.8.12)
diff --git a/find-modules/FindSharedMimeInfo.cmake b/find-modules/FindSharedMimeInfo.cmake
index 8dc6f1c4..263a5028 100644
--- a/find-modules/FindSharedMimeInfo.cmake
+++ b/find-modules/FindSharedMimeInfo.cmake
@@ -1,29 +1,56 @@
-# Try to find the shared-mime-info package
+#.rst:
+# FindSharedMimeInfo
+# ------------------
 #
-# This will define
+# Try to find the shared-mime-info package.
 #
-#   SharedMimeInfo_FOUND            - True if system has the shared-mime-info package
-#   UPDATE_MIME_DATABASE_EXECUTABLE - The update-mime-database executable
+# This will define the following variables:
 #
-# In addition, the following targets are defined:
+# ``SharedMimeInfo_FOUND``
+#     True if system has the shared-mime-info package
+# ``UPDATE_MIME_DATABASE_EXECUTABLE``
+#     The update-mime-database executable
 #
-#   SharedMimeInfo::UpdateMimeDatabase
+# and the following imported targets:
 #
-# The follow macro is available:
+# ``SharedMimeInfo::UpdateMimeDatabase``
+#     The update-mime-database executable
 #
-#     update_xdg_mimetypes(path)
+# The follow macro is available::
 #
-# Updates the XDG mime database at install time (unless the DESTDIR environment
-# variable is set, in which case it is up to package managers to perform this
-# task).
+#   update_xdg_mimetypes(<path>)
 #
+# Updates the XDG mime database at install time (unless the ``$DESTDIR``
+# environment variable is set, in which case it is up to package managers to
+# perform this task).
 
-
-# Copyright (c) 2007, Pino Toscano, <toscano.pino@tiscali.it>
-# Copyright (c) 2013-2014, Alex Merry, <alex.merry@kdemail.net>
+#=============================================================================
+# Copyright 2013-2014 Alex Merry <alex.merry@kdemail.net>
+# Copyright 2007 Pino Toscano <toscano.pino@tiscali.it>
+#
+# 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.
 #
-# Redistribution and use is allowed according to the terms of the BSD license.
-# For details see the accompanying COPYING-CMAKE-SCRIPTS file.
+# 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.
+#=============================================================================
 
 if(CMAKE_VERSION VERSION_LESS 2.8.12)
     message(FATAL_ERROR "CMake 2.8.12 is required by FindSharedMimeInfo.cmake")
diff --git a/find-modules/FindWayland.cmake b/find-modules/FindWayland.cmake
index c7c599c2..b7790e75 100644
--- a/find-modules/FindWayland.cmake
+++ b/find-modules/FindWayland.cmake
@@ -1,8 +1,12 @@
-# Try to find Wayland on a Unix system
+#.rst:
+# FindWayland
+# -----------
+#
+# Try to find Wayland on a Unix system.
 #
 # This is a component-based find module, which makes use of the COMPONENTS
 # and OPTIONAL_COMPONENTS arguments to find_module.  The following components
-# are available:
+# are available::
 #
 #   Client  Server  Cursor  Egl
 #
@@ -12,33 +16,51 @@
 # This module will define the following variables, independently of the
 # components searched for or found:
 #
-#   Wayland_FOUND      - True if (the requestion version of) Wayland is available
-#   Wayland_VERSION    - Found Wayland version
+# ``Wayland_FOUND``
+#     True if (the requestion version of) Wayland is available
+# ``Wayland_VERSION``
+#     Found Wayland version
 #
-# For each searched-for components, Wayland_<component>_FOUND will be set to true
-# if the corresponding Wayland library was found, and false otherwise.  If
-# Wayland_<component>_FOUND is true, the imported target Wayland::<component> will be
-# defined.  This module will also attempt to determine Wayland_*_VERSION variables
-# for each imported target, although Wayland_VERSION should normally be sufficient.
+# For each searched-for components, ``Wayland_<component>_FOUND`` will be set to
+# true if the corresponding Wayland library was found, and false otherwise.  If
+# ``Wayland_<component>_FOUND`` is true, the imported target
+# ``Wayland::<component>`` will be defined.  This module will also attempt to
+# determine ``Wayland_*_VERSION`` variables for each imported target, although
+# ``Wayland_VERSION`` should normally be sufficient.
 #
 # The following variable will also be defined for convenience, and for
 # compatibility with old-style find module conventions:
 #
-#   Wayland_LIBRARIES  - A list of all Wayland imported targets
+# ``Wayland_LIBRARIES``
+#     A list of all Wayland imported targets
 
 #=============================================================================
-# Copyright 2014 Martin Gräßlin <mgraesslin@kde.org>
 # Copyright 2014 Alex Merry <alex.merry@kde.org>
+# Copyright 2014 Martin Gräßlin <mgraesslin@kde.org>
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions
+# are met:
 #
-# Distributed under the OSI-approved BSD License (the "License");
-# see accompanying file COPYING-CMAKE-SCRIPTS for details.
+# 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 distributed WITHOUT ANY WARRANTY; without even the
-# implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
-# See the License for more information.
+# 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.
 #=============================================================================
-# (To distribute this file outside of extra-cmake-modules, substitute the full
-#  License text for the above reference.)
 
 include(${CMAKE_CURRENT_LIST_DIR}/../modules/ECMFindModuleHelpers.cmake)
 
diff --git a/find-modules/FindX11_XCB.cmake b/find-modules/FindX11_XCB.cmake
index e2c18a99..687a4f3d 100644
--- a/find-modules/FindX11_XCB.cmake
+++ b/find-modules/FindX11_XCB.cmake
@@ -1,17 +1,46 @@
-# - Try to find libX11-xcb
-# Once done this will define
+#.rst:
+# FindX11_XCB
+# -----------
 #
-#  X11_XCB_FOUND       - system has libX11-xcb
-#  X11_XCB_LIBRARIES   - Link these to use libX11-xcb
-#  X11_XCB_INCLUDE_DIR - the libX11-xcb include dir
-#  X11_XCB_DEFINITIONS - compiler switches required for using libX11-xcb
+# This will define the following variables:
+#
+# ``X11_XCB_FOUND``
+#     System has libX11-xcb
+# ``X11_XCB_LIBRARIES``
+#     Link these to use libX11-xcb
+# ``X11_XCB_INCLUDE_DIR``
+#     The libX11-xcb include dir
+# ``X11_XCB_DEFINITIONS``
+#     Compiler switches required for using libX11-xcb
 
-# Copyright (c) 2011 Fredrik Höglund <fredrik@kde.org>
-# Copyright (c) 2008 Helio Chissini de Castro, <helio@kde.org>
-# Copyright (c) 2007 Matthias Kretz, <kretz@kde.org>
+#=============================================================================
+# Copyright 2011 Fredrik Höglund <fredrik@kde.org>
+# Copyright 2008 Helio Chissini de Castro <helio@kde.org>
+# Copyright 2007 Matthias Kretz <kretz@kde.org>
+#
+# 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.
 #
-# Redistribution and use is allowed according to the terms of the BSD license.
-# For details see the accompanying COPYING-CMAKE-SCRIPTS file.
+# 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.
+#=============================================================================
 
 IF (NOT WIN32)
   # use pkg-config to get the directories and then use these values
diff --git a/find-modules/FindXCB.cmake b/find-modules/FindXCB.cmake
index a900a624..dd876b21 100644
--- a/find-modules/FindXCB.cmake
+++ b/find-modules/FindXCB.cmake
@@ -1,8 +1,12 @@
-# Try to find XCB on a Unix system
+#.rst:
+# FindXCB
+# -------
 #
-# This is a component-based find module, which makes use of the COMPONENTS
-# and OPTIONAL_COMPONENTS arguments to find_module.  The following components
-# are available:
+# Try to find XCB on a Unix system.
+#
+# This is a component-based find module, which makes use of the COMPONENTS and
+# OPTIONAL_COMPONENTS arguments to find_module.  The following components are
+# available::
 #
 #   XCB
 #   ATOM         AUX          COMPOSITE    CURSOR       DAMAGE
@@ -19,34 +23,52 @@
 # This module will define the following variables, independently of the
 # components searched for or found:
 #
-#   XCB_FOUND      - True if (the requestion version of) xcb is available
-#   XCB_VERSION    - Found xcb version
+# ``XCB_FOUND``
+#     True if (the requestion version of) xcb is available
+# ``XCB_VERSION``
+#     Found xcb version
 #
-# For each searched-for components, XCB_<component>_FOUND will be set to true
-# if the corresponding xcb library was found, and false otherwise.  If
-# XCB_<component>_FOUND is true, the imported target XCB::<component> will be
-# defined.  This module will also attempt to determine XCB_*_VERSION variables
-# for each imported target, although XCB_VERSION should normally be sufficient.
+# For each searched-for components, ``XCB_<component>_FOUND`` will be set to
+# true if the corresponding xcb library was found, and false otherwise.  If
+# ``XCB_<component>_FOUND`` is true, the imported target ``XCB::<component>``
+# will be defined.  This module will also attempt to determine
+# ``XCB_*_VERSION`` variables for each imported target, although
+# ``XCB_VERSION`` should normally be sufficient.
 #
 # The following variable will also be defined for convenience, and for
 # compatibility with old-style find module conventions:
 #
-#   XCB_LIBRARIES  - A list of all XCB imported targets
+# ``XCB_LIBRARIES``
+#     A list of all XCB imported targets
 
 #=============================================================================
 # Copyright 2011 Fredrik Höglund <fredrik@kde.org>
 # Copyright 2013 Martin Gräßlin <mgraesslin@kde.org>
 # Copyright 2014 Alex Merry <alex.merry@kde.org>
 #
-# Distributed under the OSI-approved BSD License (the "License");
-# see accompanying file COPYING-CMAKE-SCRIPTS for details.
+# 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 distributed WITHOUT ANY WARRANTY; without even the
-# implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
-# See the License for more information.
+# 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.
 #=============================================================================
-# (To distribute this file outside of extra-cmake-modules, substitute the full
-#  License text for the above reference.)
 
 include(${CMAKE_CURRENT_LIST_DIR}/../modules/ECMFindModuleHelpers.cmake)