Add Sphinx documentation

The `Makefile` can be used to generate the documentation:

    make html

`sphinx-build` must be in the path.

.gitignore

@@ -1094,6 +1094,9 @@ cgal_test_with_cmake.log
 # File created by the Semantic Bovinator (an Emacs package)
 semantic.cache
 
+# Python cache files
+*.pyc
+
 # Files produced by a Qt compilation/execution
 .qglviewer.xml
 *.moc

Installation/cmake/modules/CGAL_SetupBoost.cmake

@@ -1,3 +1,15 @@
+#.rst:
+# CGAL_SetupBoost
+# ---------------
+#
+# The module searchs for the `Boost` headers and library, by calling
+#
+# .. code-block:: cmake
+#
+#    find_package(Boost)
+#
+# and defines the function :command:`use_CGAL_Boost_support`.
+
 if ( CGAL_Boost_Setup )
   return()
 endif()
@@ -40,6 +52,21 @@ message( STATUS "Boost libraries:    ${Boost_LIBRARIES}" )
 
 set ( CGAL_USE_BOOST 1 )
 
+
+#.rst:
+# Provided Functions
+# ^^^^^^^^^^^^^^^^^^
+#
+# .. command:: use_CGAL_Boost_support
+#
+#    Link the target with the `Boost` libraries::
+#
+#      use_CGAL_Boost_support( target [INTERFACE] )
+#
+#    If the option ``INTERFACE`` is passed, the dependencies are
+#    added using :command:`target_link_libraries` with the ``INTERFACE``
+#    keyword, or ``PUBLIC`` otherwise.
+
 function(use_CGAL_Boost_support target)
   if(ARGV1 STREQUAL INTERFACE)
     set(keyword INTERFACE)

Installation/cmake/modules/CGAL_SetupCGALDependencies.cmake

@@ -1,22 +1,82 @@
+#.rst:
+# CGAL_SetupCGALDependencies
+# --------------------------
+#
+# The module searchs for the dependencies of the CGAL library:
+#   - the `GMP/MPFR` couple,
+#   - `LEDA` (optional)
+#   - the `Boost` libraries (mostly the header-only libraries)
+#
+# and defines the variable :variable:`CGAL_FOUND` and the function
+# :command:`CGAL_setup_CGAL_dependencies`.
+#
+# Module Input Variables
+# ^^^^^^^^^^^^^^^^^^^^^^
+# .. variable:: CGAL_DISABLE_GMP
+#
+#    If set, the `GMP` library will not be used. If
+#    :variable:`WITH_LEDA` is not used either, a efficient exact
+#    number types are used by CGAL kernels for exact computation.
+#
+# .. variable:: WITH_LEDA
+#
+#    If set, the `LEDA` library will be searched and used to provide
+#    the exact number types used by CGAL kernels.
+#
+# .. variable:: CGAL_HEADER_ONLY
+#
+#    Set this variable if you are using the CGAL libraries as
+#    header-only libraries.
+#
 if(CGAL_SetupCGALDependencies_included)
   return()
 endif()
 set(CGAL_SetupCGALDependencies_included TRUE)
 
+#.rst:
+# Used Modules
+# ^^^^^^^^^^^^
+#   - :module:`CGAL_SetupGMP`
 if(NOT CGAL_DISABLE_GMP)
   include(CGAL_SetupGMP)
 endif()
 
+#.rst:
+#   - :module:`CGAL_SetupLEDA`
 if(WITH_LEDA)
   include(CGAL_SetupLEDA)
 endif()
 
+#.rst:
+#   - :module:`CGAL_SetupBoost`
 include(CGAL_SetupBoost)
 
+#.rst:
+# Result Variables
+# ^^^^^^^^^^^^^^^^
+#
+# .. variable:: CGAL_FOUND
+#
+#    Set to `TRUE` if the dependencies of CGAL were found.
 if(Boost_FOUND)
   set(CGAL_FOUND TRUE)
 endif()
 
+#.rst:
+#
+# Provided Functions
+# ^^^^^^^^^^^^^^^^^^
+#
+# .. command:: CGAL_setup_CGAL_dependencies
+#
+#   Link the target with the dependencies of CGAL::
+#
+#     CGAL_setup_CGAL_dependencies( target [INTERFACE] )
+#
+#   If the option ``INTERFACE`` is passed, the dependencies are
+#   added using :command:`target_link_libraries` with the ``INTERFACE``
+#   keyword, or ``PUBLIC`` otherwise.
+#
 function(CGAL_setup_CGAL_dependencies target)
   if(ARGV1 STREQUAL INTERFACE)
     set(keyword INTERFACE)

Installation/cmake/modules/CGAL_SetupCGAL_CoreDependencies.cmake

@@ -1,8 +1,34 @@
+#.rst:
+# CGAL_SetupCGAL_CoreDependencies
+# -------------------------------
+#
+# The module searchs for the dependencies of the `CGAL_Core` library:
+#   - the `GMP/MPFR` couple,
+#
+# and defines the variable :variable:`CGAL_Core_FOUND` and the function
+# :command:`CGAL_setup_CGAL_Core_dependencies`.
+#
+# Module Input Variables
+# ^^^^^^^^^^^^^^^^^^^^^^
+# - :variable:`CGAL_DISABLE_GMP`
+
 if(CGAL_SetupCGAL_CoreDependencies_included)
   return()
 endif()
 set(CGAL_SetupCGAL_CoreDependencies_included TRUE)
 
+#.rst:
+# Used Modules
+# ^^^^^^^^^^^^
+#   - :module:`CGAL_SetupGMP`
+#
+# Result Variables
+# ^^^^^^^^^^^^^^^^
+#
+# .. variable:: CGAL_Core_FOUND
+#
+#    Set to `TRUE` if the dependencies of `CGAL_Core` were found.
+
 if(NOT CGAL_DISABLE_GMP)
   include(CGAL_SetupGMP)
   if(GMP_FOUND)
@@ -10,6 +36,21 @@ if(NOT CGAL_DISABLE_GMP)
   endif()
 endif()
 
+#.rst:
+#
+# Provided Functions
+# ^^^^^^^^^^^^^^^^^^
+#
+# .. command:: CGAL_setup_CGAL_Core_dependencies
+#
+#   Link the target with the dependencies of `CGAL_Core`::
+#
+#     CGAL_setup_CGAL_Core_dependencies( target [INTERFACE] )
+#
+#   If the option ``INTERFACE`` is passed, the dependencies are
+#   added using :command:`target_link_libraries` with the ``INTERFACE``
+#   keyword, or ``PUBLIC`` otherwise.
+#
 function(CGAL_setup_CGAL_Core_dependencies target)
   if(ARGV1 STREQUAL INTERFACE)
     set(keyword INTERFACE)

Installation/cmake/modules/CGAL_SetupCGAL_ImageIODependencies.cmake

@@ -1,14 +1,46 @@
+#.rst:
+# CGAL_SetupCGAL_ImageIODependencies
+# ----------------------------------
+#
+# The module searchs for the dependencies of the `CGAL_ImageIO` library:
+#   - the `Zlib` library (optional)
+#
+# by calling
+#
+# .. code-block:: cmake
+#
+#    find_package(ZLIB)
+#
+# and defines the variable :variable:`CGAL_ImageIO_FOUND` and the function
+# :command:`CGAL_setup_CGAL_ImageIO_dependencies`.
+#
 if(CGAL_SetupCGAL_ImageIODependencies_included)
   return()
 endif()
 set(CGAL_SetupCGAL_ImageIODependencies_included TRUE)
 
+#.rst:
+# Used Modules
+# ^^^^^^^^^^^^
+#   - :module:`FindZLIB`
 find_package( ZLIB )
 
 define_property(TARGET PROPERTY CGAL_TARGET_USES_ZLIB
   BRIEF_DOCS "Tells if the target uses ZLIB as a dependency"
   FULL_DOCS "Tells if the target uses ZLIB as a dependency")
 
+#.rst:
+# Result Variables
+# ^^^^^^^^^^^^^^^^
+#
+# .. variable:: CGAL_ImageIO_USE_ZLIB
+#
+#    Set to `TRUE` if `CGAL_ImageIO` was compiled with `Zlib`.
+#
+# .. variable:: CGAL_ImageIO_FOUND
+#
+#    Always set to `TRUE`.
+
 if(ZLIB_FOUND)
   set(CGAL_ImageIO_USE_ZLIB ON CACHE BOOL "CGAL_ImageIO uses ZLIB")
 endif(ZLIB_FOUND)

Installation/cmake/modules/CGAL_SetupCGAL_Qt5Dependencies.cmake

@@ -1,8 +1,31 @@
+#.rst:
+# CGAL_SetupCGAL_Qt5Dependencies
+# ------------------------------
+#
+# The module searchs for the dependencies of the `CGAL_Qt5` library:
+#   - the `Qt5` libraries
+#
+# by calling
+#
+# .. code-block:: cmake
+#
+#    find_package(Qt5 QUIET COMPONENTS OpenGL Svg)
+#    find_package(OpenGL QUIET)
+#
+# and defines the variable :variable:`CGAL_Qt5_FOUND` and the function
+# :command:`CGAL_setup_CGAL_Qt5_dependencies`.
+#
+
 if(CGAL_SetupCGAL_Qt5Dependencies_included)
   return()
 endif()
 set(CGAL_SetupCGAL_Qt5Dependencies_included TRUE)
 
+#.rst:
+# Used Modules
+# ^^^^^^^^^^^^
+#   - :module:`Qt5Config`
+#   - :module:`FindOpenGL`
 find_package(Qt5 QUIET COMPONENTS OpenGL Svg)
 find_package(OpenGL QUIET)
 
@@ -20,6 +43,14 @@ if(NOT OPENGL_FOUND)
   set(CGAL_Qt5_MISSING_DEPS "${CGAL_Qt5_MISSING_DEPS} OpenGL")
 endif()
 
+#.rst:
+# Result Variables
+# ^^^^^^^^^^^^^^^^
+#
+# .. variable:: CGAL_Qt5_FOUND
+#
+#    Set to `TRUE` if the dependencies of `CGAL_Qt5` were found.
+#
 if(NOT CGAL_Qt5_MISSING_DEPS)
   set(CGAL_Qt5_FOUND TRUE)
 endif()
@@ -34,6 +65,21 @@ endif()
 #message( STATUS "moc executable:      ${QT_MOC_EXECUTABLE}" )
 #message( STATUS "uic executable:      ${QT_UIC_EXECUTABLE}" )
 
+#.rst:
+#
+# Provided Functions
+# ^^^^^^^^^^^^^^^^^^
+#
+# .. command:: CGAL_setup_CGAL_Qt5_dependencies
+#
+#   Link the target with the dependencies of `CGAL_Qt5`::
+#
+#     CGAL_setup_CGAL_Qt5_dependencies( target [INTERFACE] )
+#
+#   If the option ``INTERFACE`` is passed, the dependencies are
+#   added using :command:`target_link_libraries` with the ``INTERFACE``
+#   keyword, or ``PUBLIC`` otherwise.
+#
 function(CGAL_setup_CGAL_Qt5_dependencies target)
   if(ARGV1 STREQUAL INTERFACE)
     set(keyword INTERFACE)

Installation/cmake/modules/CGAL_SetupGMP.cmake

@@ -1,3 +1,17 @@
+#.rst:
+# CGAL_SetupGMP
+# -------------
+#
+# The module searchs for the `GMP` and `MPFR` headers and libraries,
+# by calling
+#
+# .. code-block:: cmake
+#
+#    find_package(GMP)
+#    find_package(MPFR)
+#
+# and defines the function :command:`use_CGAL_GMP_support`.
+
 if(CGAL_SetupGMP_included OR CGAL_DISABLE_GMP)
   return()
 endif()
@@ -6,6 +20,20 @@ set(CGAL_SetupGMP_included TRUE)
 find_package(GMP)
 find_package(MPFR)
 
+#.rst:
+# Provided Functions
+# ^^^^^^^^^^^^^^^^^^
+#
+# .. command:: use_CGAL_GMP_support
+#
+#    Link the target with the `GMP` and `MPFR` libraries::
+#
+#      use_CGAL_GMP_support( target [INTERFACE] )
+#
+#    If the option ``INTERFACE`` is passed, the dependencies are
+#    added using :command:`target_link_libraries` with the ``INTERFACE``
+#    keyword, or ``PUBLIC`` otherwise.
+
 function(use_CGAL_GMP_support target)
   if(ARGV1 STREQUAL INTERFACE)
     set(keyword INTERFACE)

Installation/cmake/modules/CGAL_SetupLEDA.cmake

@@ -1,3 +1,15 @@
+#.rst:
+# CGAL_SetupLEDA
+# --------------
+#
+# The module searchs for the `LEDA` headers and library, by calling
+#
+# .. code-block:: cmake
+#
+#    find_package(LEDA)
+#
+# and defines the function :command:`use_CGAL_LEDA_support`.
+
 if(CGAL_SetupLEDA_included)
   return()
 endif()
@@ -5,6 +17,20 @@ set(CGAL_SetupLEDA_included TRUE)
 
 find_package(LEDA)
 
+#.rst:
+# Provided Functions
+# ^^^^^^^^^^^^^^^^^^
+#
+# .. command:: use_CGAL_LEDA_support
+#
+#    Link the target with the `LEDA` libraries::
+#
+#      use_CGAL_LEDA_support( target [INTERFACE] )
+#
+#    If the option ``INTERFACE`` is passed, the dependencies are
+#    added using :command:`target_link_libraries` with the ``INTERFACE``
+#    keyword, or ``PUBLIC`` otherwise.
+
 function(use_CGAL_LEDA_support target)
   if(ARGV1 STREQUAL INTERFACE)
     set(keyword INTERFACE)

Installation/cmake/modules/Help/CGAL_SetupBoost.rst

@@ -0,0 +1 @@
+.. cmake-module:: ../CGAL_SetupBoost.cmake

Installation/cmake/modules/Help/CGAL_SetupCGALDependencies.rst

@@ -0,0 +1 @@
+.. cmake-module:: ../CGAL_SetupCGALDependencies.cmake

Installation/cmake/modules/Help/CGAL_SetupCGAL_CoreDependencies.rst

@@ -0,0 +1 @@
+.. cmake-module:: ../CGAL_SetupCGAL_CoreDependencies.cmake

Installation/cmake/modules/Help/CGAL_SetupCGAL_ImageIODependencies.rst

@@ -0,0 +1 @@
+.. cmake-module:: ../CGAL_SetupCGAL_ImageIODependencies.cmake

Installation/cmake/modules/Help/CGAL_SetupCGAL_Qt5Dependencies.rst

@@ -0,0 +1 @@
+.. cmake-module:: ../CGAL_SetupCGAL_Qt5Dependencies.cmake

Installation/cmake/modules/Help/CGAL_SetupGMP.rst

@@ -0,0 +1 @@
+.. cmake-module:: ../CGAL_SetupGMP.cmake

Installation/cmake/modules/Help/CGAL_SetupLEDA.rst

@@ -0,0 +1 @@
+.. cmake-module:: ../CGAL_SetupLEDA.cmake

Installation/cmake/modules/Help/cmake.py

@@ -0,0 +1,393 @@
+#=============================================================================
+# 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 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 CMakeModule(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 as error:
+            raise self.severe('Problems with "%s" directive path:\n'
+                              'Cannot encode input file path "%s" '
+                              '(wrong locale?).' %
+                              (self.name, SafeString(path)))
+        except IOError as 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 _cmake_index_entry:
+    def __init__(self, desc):
+        self.desc = desc
+
+    def __call__(self, title, targetid, main = 'main'):
+#        return (targetid, title, main, targetid, '', '', 0)
+        return ('pair', u'%s ; %s' % (self.desc, title), targetid, main)
+
+_cmake_index_objs = {
+    'command':    _cmake_index_entry('command'),
+    'generator':  _cmake_index_entry('generator'),
+    'manual':     _cmake_index_entry('manual'),
+    'module':     _cmake_index_entry('module'),
+    'policy':     _cmake_index_entry('policy'),
+    'prop_cache': _cmake_index_entry('cache property'),
+    'prop_dir':   _cmake_index_entry('directory property'),
+    'prop_gbl':   _cmake_index_entry('global property'),
+    'prop_inst':  _cmake_index_entry('installed file property'),
+    'prop_sf':    _cmake_index_entry('source file property'),
+    'prop_test':  _cmake_index_entry('test property'),
+    'prop_tgt':   _cmake_index_entry('target property'),
+    'variable':   _cmake_index_entry('variable'),
+    }
+
+def _cmake_object_inventory(env, document, line, objtype, targetid):
+    inv = env.domaindata['cmake']['objects']
+    if targetid in inv:
+        document.reporter.warning(
+            'CMake object "%s" also described in "%s".' %
+            (targetid, env.doc2path(inv[targetid][0])), line=line)
+    inv[targetid] = (env.docname, objtype)
+
+class CMakeTransform(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.
+           The cmake --help-*-list commands also depend on this convention.
+           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 cmake domain objects.
+        objtype, sep, tail = env.docname.rpartition('/')
+        make_index_entry = _cmake_index_objs.get(objtype)
+        if make_index_entry:
+            title = self.parse_title(env.docname)
+            # Insert the object link target.
+            if objtype == 'command':
+                targetname = title.lower()
+            else:
+                targetname = title
+            targetid = '%s:%s' % (objtype, targetname)
+            targetnode = nodes.target('', '', ids=[targetid])
+            self.document.note_explicit_target(targetnode)
+            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 cmake domain object inventory
+            _cmake_object_inventory(env, self.document, 1, objtype, targetid)
+
+class CMakeObject(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):
+        if self.objtype == 'command':
+           targetname = name.lower()
+        else:
+           targetname = name
+        targetid = '%s:%s' % (self.objtype, targetname)
+        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)
+            _cmake_object_inventory(self.env, self.state.document,
+                                    self.lineno, self.objtype, targetid)
+
+        make_index_entry = _cmake_index_objs.get(self.objtype)
+        if make_index_entry:
+            self.indexnode['entries'].append(make_index_entry(name, targetid))
+
+class CMakeXRefRole(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):
+        # Translate CMake command cross-references of the form:
+        #  `command_name(SUB_COMMAND)`
+        # to have an explicit target:
+        #  `command_name(SUB_COMMAND) <command_name>`
+        if typ == 'cmake:command':
+            m = CMakeXRefRole._re_sub.match(text)
+            if m:
+                text = '%s <%s>' % (text, m.group(1))
+        # CMake cross-reference targets frequently contain '<' so escape
+        # any explicit `<target>` with '<' not preceded by whitespace.
+        while True:
+            m = CMakeXRefRole._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)
+
+    # We cannot insert index nodes using the result_nodes method
+    # because CMakeXRefRole is processed before substitution_reference
+    # nodes are evaluated so target nodes (with 'ids' fields) would be
+    # duplicated in each evaluted substitution replacement.  The
+    # docutils substitution transform does not allow this.  Instead we
+    # use our own CMakeXRefTransform below to add index entries after
+    # substitutions are completed.
+    #
+    # def result_nodes(self, document, env, node, is_ref):
+    #     pass
+
+class CMakeXRefTransform(Transform):
+
+    # Run this transform early since we insert nodes we want
+    # treated as if they were written in the documents, but
+    # after the sphinx (210) and docutils (220) substitutions.
+    default_priority = 221
+
+    def apply(self):
+        env = self.document.settings.env
+
+        # Find CMake cross-reference nodes and add index and target
+        # nodes for them.
+        for ref in self.document.traverse(addnodes.pending_xref):
+            if not ref['refdomain'] == 'cmake':
+                continue
+
+            objtype = ref['reftype']
+            make_index_entry = _cmake_index_objs.get(objtype)
+            if not make_index_entry:
+                continue
+
+            objname = ref['reftarget']
+            targetnum = env.new_serialno('index-%s:%s' % (objtype, objname))
+
+            targetid = 'index-%s-%s:%s' % (targetnum, objtype, objname)
+            targetnode = nodes.target('', '', ids=[targetid])
+            self.document.note_explicit_target(targetnode)
+
+            indexnode = addnodes.index()
+            indexnode['entries'] = [make_index_entry(objname, targetid, '')]
+            ref.replace_self([indexnode, targetnode, ref])
+
+class CMakeDomain(Domain):
+    """CMake domain."""
+    name = 'cmake'
+    label = 'CMake'
+    object_types = {
+        'command':    ObjType('command',    'command'),
+        'generator':  ObjType('generator',  'generator'),
+        'variable':   ObjType('variable',   'variable'),
+        'module':     ObjType('module',     'module'),
+        'policy':     ObjType('policy',     'policy'),
+        'prop_cache': ObjType('prop_cache', 'prop_cache'),
+        'prop_dir':   ObjType('prop_dir',   'prop_dir'),
+        'prop_gbl':   ObjType('prop_gbl',   'prop_gbl'),
+        'prop_inst':  ObjType('prop_inst',  'prop_inst'),
+        'prop_sf':    ObjType('prop_sf',    'prop_sf'),
+        'prop_test':  ObjType('prop_test',  'prop_test'),
+        'prop_tgt':   ObjType('prop_tgt',   'prop_tgt'),
+        'manual':     ObjType('manual',     'manual'),
+    }
+    directives = {
+        'command':    CMakeObject,
+        'variable':   CMakeObject,
+        # Other object types cannot be created except by the CMakeTransform
+        # 'generator':  CMakeObject,
+        # 'module':     CMakeObject,
+        # 'policy':     CMakeObject,
+        # 'prop_cache': CMakeObject,
+        # 'prop_dir':   CMakeObject,
+        # 'prop_gbl':   CMakeObject,
+        # 'prop_inst':  CMakeObject,
+        # 'prop_sf':    CMakeObject,
+        # 'prop_test':  CMakeObject,
+        # 'prop_tgt':   CMakeObject,
+        # 'manual':     CMakeObject,
+    }
+    roles = {
+        'command':    CMakeXRefRole(fix_parens = True, lowercase = True),
+        'generator':  CMakeXRefRole(),
+        'variable':   CMakeXRefRole(),
+        'module':     CMakeXRefRole(),
+        'policy':     CMakeXRefRole(),
+        'prop_cache': CMakeXRefRole(),
+        'prop_dir':   CMakeXRefRole(),
+        'prop_gbl':   CMakeXRefRole(),
+        'prop_inst':  CMakeXRefRole(),
+        'prop_sf':    CMakeXRefRole(),
+        'prop_test':  CMakeXRefRole(),
+        'prop_tgt':   CMakeXRefRole(),
+        'manual':     CMakeXRefRole(),
+    }
+    initial_data = {
+        'objects': {},  # fullname -> docname, objtype
+    }
+
+    def clear_doc(self, docname):
+        to_clear = set()
+        for fullname, (fn, _) in self.data['objects'].items():
+            if fn == docname:
+                to_clear.add(fullname)
+        for fullname in to_clear:
+            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'].items():
+            yield (refname, refname, type, docname, refname, 1)
+
+def setup(app):
+    app.add_directive('cmake-module', CMakeModule)
+    app.add_transform(CMakeTransform)
+    app.add_transform(CMakeXRefTransform)
+    app.add_domain(CMakeDomain)

Installation/cmake/modules/Help/conf.py

@@ -0,0 +1,340 @@
+# -*- coding: utf-8 -*-
+#
+# CGAL CMake Modules documentation build configuration file, created by
+# sphinx-quickstart on Fri Sep 23 22:51:32 2016.
+#
+# This file is execfile()d with the current directory set to its
+# containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+import os
+import sys
+sys.path.insert(0, os.path.abspath('.'))
+
+# -- General configuration ------------------------------------------------
+
+primary_domain = 'cmake'
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#
+# needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = ['cmake']
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+# source_suffix = ['.rst', '.md']
+source_suffix = '.rst'
+
+# The encoding of source files.
+#
+# source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'CGAL CMake Modules'
+copyright = u'2016, The CGAL Project'
+author = u'The CGAL Project'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = u'4.10'
+# The full version, including alpha/beta/rc tags.
+release = u'4.10'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#
+# today = ''
+#
+# Else, today_fmt is used as the format for a strftime call.
+#
+# today_fmt = '%B %d, %Y'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This patterns also effect to html_static_path and html_extra_path
+exclude_patterns = []
+
+# The reST default role (used for this markup: `text`) to use for all
+# documents.
+#
+# default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#
+# add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#
+# add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#
+# show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# A list of ignored prefixes for module index sorting.
+# modindex_common_prefix = []
+
+# If true, keep warnings as "system message" paragraphs in the built documents.
+# keep_warnings = False
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = False
+
+
+# -- Options for HTML output ----------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'alabaster'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#
+# html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+# html_theme_path = []
+
+# The name for this set of Sphinx documents.
+# "<project> v<release> documentation" by default.
+#
+# html_title = u'CGAL CMake Modules v4.10'
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+#
+# html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#
+# html_logo = None
+
+# The name of an image file (relative to this directory) to use as a favicon of
+# the docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#
+# html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# Add any extra paths that contain custom files (such as robots.txt or
+# .htaccess) here, relative to this directory. These files are copied
+# directly to the root of the documentation.
+#
+# html_extra_path = []
+
+# If not None, a 'Last updated on:' timestamp is inserted at every page
+# bottom, using the given strftime format.
+# The empty string is equivalent to '%b %d, %Y'.
+#
+# html_last_updated_fmt = None
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#
+# html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#
+# html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#
+# html_additional_pages = {}
+
+# If false, no module index is generated.
+#
+# html_domain_indices = True
+
+# If false, no index is generated.
+#
+# html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#
+# html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+#
+# html_show_sourcelink = True
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+#
+# html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+#
+# html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it.  The value of this option must be the
+# base URL from which the finished HTML is served.
+#
+# html_use_opensearch = ''
+
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+# html_file_suffix = None
+
+# Language to be used for generating the HTML full-text search index.
+# Sphinx supports the following languages:
+#   'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja'
+#   'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr', 'zh'
+#
+# html_search_language = 'en'
+
+# A dictionary with options for the search language support, empty by default.
+# 'ja' uses this config value.
+# 'zh' user can custom change `jieba` dictionary path.
+#
+# html_search_options = {'type': 'default'}
+
+# The name of a javascript file (relative to the configuration directory) that
+# implements a search results scorer. If empty, the default will be used.
+#
+# html_search_scorer = 'scorer.js'
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'CGALModulesdoc'
+
+# -- Options for LaTeX output ---------------------------------------------
+
+latex_elements = {
+     # The paper size ('letterpaper' or 'a4paper').
+     #
+     # 'papersize': 'letterpaper',
+
+     # The font size ('10pt', '11pt' or '12pt').
+     #
+     # 'pointsize': '10pt',
+
+     # Additional stuff for the LaTeX preamble.
+     #
+     # 'preamble': '',
+
+     # Latex figure (float) alignment
+     #
+     # 'figure_align': 'htbp',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+    (master_doc, 'CGALModules.tex', u'CGAL CMake Modules Documentation',
+     u'Laurent Rineau', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#
+# latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#
+# latex_use_parts = False
+
+# If true, show page references after internal links.
+#
+# latex_show_pagerefs = False
+
+# If true, show URL addresses after external links.
+#
+# latex_show_urls = False
+
+# Documents to append as an appendix to all manuals.
+#
+# latex_appendices = []
+
+# It false, will not define \strong, \code, 	itleref, \crossref ... but only
+# \sphinxstrong, ..., \sphinxtitleref, ... To help avoid clash with user added
+# packages.
+#
+# latex_keep_old_macro_names = True
+
+# If false, no module index is generated.
+#
+# latex_domain_indices = True
+
+
+# -- Options for manual page output ---------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    (master_doc, 'cgalmodules', u'CGAL CMake Modules Documentation',
+     [author], 1)
+]
+
+# If true, show URL addresses after external links.
+#
+# man_show_urls = False
+
+
+# -- Options for Texinfo output -------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+    (master_doc, 'CGALModules', u'CGAL CMake Modules Documentation',
+     author, 'CGALModules', 'One line description of project.',
+     'Miscellaneous'),
+]
+
+# Documents to append as an appendix to all manuals.
+#
+# texinfo_appendices = []
+
+# If false, no module index is generated.
+#
+# texinfo_domain_indices = True
+
+# How to display URL addresses: 'footnote', 'no', or 'inline'.
+#
+# texinfo_show_urls = 'footnote'
+
+# If true, do not generate a @detailmenu in the "Top" node's menu.
+#
+# texinfo_no_detailmenu = False

Installation/cmake/modules/Help/index.rst

@@ -0,0 +1,34 @@
+.. CGAL CMake Modules documentation master file, created by
+   sphinx-quickstart on Fri Sep 23 22:51:32 2016.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to CGAL CMake Modules's documentation!
+==============================================
+
+Contents:
+
+.. toctree::
+   :maxdepth: 1
+
+   CGAL_SetupGMP
+   CGAL_SetupLEDA
+   CGAL_SetupBoost
+   CGAL_SetupCGALDependencies
+   CGAL_SetupCGAL_CoreDependencies
+   CGAL_SetupCGAL_Qt5Dependencies
+   CGAL_SetupCGAL_ImageIODependencies
+
+TODO
+^^^^
+- ``CGAL_SetupDependencies.cmake``
+- ``CGAL_SetupFlags.cmake``
+- ``CGAL_SetupVLD.cmake``
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+

Installation/cmake/modules/Makefile

@@ -0,0 +1,225 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+PAPER         =
+BUILDDIR      = build
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) Help
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) Help
+
+.PHONY: help
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html       to make standalone HTML files"
+	@echo "  dirhtml    to make HTML files named index.html in directories"
+	@echo "  singlehtml to make a single large HTML file"
+	@echo "  pickle     to make pickle files"
+	@echo "  json       to make JSON files"
+	@echo "  htmlhelp   to make HTML files and a HTML help project"
+	@echo "  qthelp     to make HTML files and a qthelp project"
+	@echo "  applehelp  to make an Apple Help Book"
+	@echo "  devhelp    to make HTML files and a Devhelp project"
+	@echo "  epub       to make an epub"
+	@echo "  epub3      to make an epub3"
+	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
+	@echo "  latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
+	@echo "  text       to make text files"
+	@echo "  man        to make manual pages"
+	@echo "  texinfo    to make Texinfo files"
+	@echo "  info       to make Texinfo files and run them through makeinfo"
+	@echo "  gettext    to make PO message catalogs"
+	@echo "  changes    to make an overview of all changed/added/deprecated items"
+	@echo "  xml        to make Docutils-native XML files"
+	@echo "  pseudoxml  to make pseudoxml-XML files for display purposes"
+	@echo "  linkcheck  to check all external links for integrity"
+	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
+	@echo "  coverage   to run coverage check of the documentation (if enabled)"
+	@echo "  dummy      to check syntax errors of document sources"
+
+.PHONY: clean
+clean:
+	rm -rf $(BUILDDIR)/*
+
+.PHONY: html
+html:
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+.PHONY: dirhtml
+dirhtml:
+	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+.PHONY: singlehtml
+singlehtml:
+	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+	@echo
+	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+.PHONY: pickle
+pickle:
+	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+	@echo
+	@echo "Build finished; now you can process the pickle files."
+
+.PHONY: json
+json:
+	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+	@echo
+	@echo "Build finished; now you can process the JSON files."
+
+.PHONY: htmlhelp
+htmlhelp:
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+	@echo
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
+	      ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+.PHONY: qthelp
+qthelp:
+	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+	@echo
+	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
+	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/CGALModules.qhcp"
+	@echo "To view the help file:"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/CGALModules.qhc"
+
+.PHONY: applehelp
+applehelp:
+	$(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp
+	@echo
+	@echo "Build finished. The help book is in $(BUILDDIR)/applehelp."
+	@echo "N.B. You won't be able to view it unless you put it in" \
+	      "~/Library/Documentation/Help or install it in your application" \
+	      "bundle."
+
+.PHONY: devhelp
+devhelp:
+	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+	@echo
+	@echo "Build finished."
+	@echo "To view the help file:"
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/CGALModules"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/CGALModules"
+	@echo "# devhelp"
+
+.PHONY: epub
+epub:
+	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+	@echo
+	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+.PHONY: epub3
+epub3:
+	$(SPHINXBUILD) -b epub3 $(ALLSPHINXOPTS) $(BUILDDIR)/epub3
+	@echo
+	@echo "Build finished. The epub3 file is in $(BUILDDIR)/epub3."
+
+.PHONY: latex
+latex:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo
+	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+	@echo "Run \`make' in that directory to run these through (pdf)latex" \
+	      "(use \`make latexpdf' here to do that automatically)."
+
+.PHONY: latexpdf
+latexpdf:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through pdflatex..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+.PHONY: latexpdfja
+latexpdfja:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through platex and dvipdfmx..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+.PHONY: text
+text:
+	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+	@echo
+	@echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+.PHONY: man
+man:
+	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+	@echo
+	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+.PHONY: texinfo
+texinfo:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo
+	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
+	@echo "Run \`make' in that directory to run these through makeinfo" \
+	      "(use \`make info' here to do that automatically)."
+
+.PHONY: info
+info:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo "Running Texinfo files through makeinfo..."
+	make -C $(BUILDDIR)/texinfo info
+	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
+
+.PHONY: gettext
+gettext:
+	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
+	@echo
+	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
+
+.PHONY: changes
+changes:
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+	@echo
+	@echo "The overview file is in $(BUILDDIR)/changes."
+
+.PHONY: linkcheck
+linkcheck:
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in $(BUILDDIR)/linkcheck/output.txt."
+
+.PHONY: doctest
+doctest:
+	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+	@echo "Testing of doctests in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/doctest/output.txt."
+
+.PHONY: coverage
+coverage:
+	$(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage
+	@echo "Testing of coverage in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/coverage/python.txt."
+
+.PHONY: xml
+xml:
+	$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
+	@echo
+	@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
+
+.PHONY: pseudoxml
+pseudoxml:
+	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
+	@echo
+	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
+
+.PHONY: dummy
+dummy:
+	$(SPHINXBUILD) -b dummy $(ALLSPHINXOPTS) $(BUILDDIR)/dummy
+	@echo
+	@echo "Build finished. Dummy builder generates no files."