docs: Switch to new theme and fix issues [skip ci]

doc/DOC.md

+Cabal documentation
+===================
+
+###How to build it
+
+* > pip install sphinx
+* > sphinx-build doc html
+* if you are missing dependencies, install them with pip as needed
+¯\\\_(ツ)_/¯
+* Python on Mac OS X dislikes LC\_CTYPE=UTF-8, unset the env var in
+terminal preferences and instead set LC\_ALL=en_US.UTF-8 or something

doc/bugs-and-stability.rst

+Reporting Bugs and Stability of Cabal Interfaces
+================================================
+
+.. toctree::
+   misc
+

doc/concepts-and-development.rst

+Package Concepts and Development
+================================
+
+.. toctree::
+   :maxdepth: 2
+
+   developing-packages

doc/conf.py

+# -*- coding: utf-8 -*-
+#
+# GHC Users Guide documentation build configuration file
+#
+# This file is execfile()d with the current directory set to its
+# containing dir.
+#
+import sys
+import os
+import sphinx_rtd_theme
+
+# Support for :base-ref:, etc.
+sys.path.insert(0, os.path.abspath('.'))
+version = "1.25"
+
+extensions = ['sphinx.ext.extlinks']
+
+templates_path = ['.templates']
+source_suffix = '.rst'
+source_encoding = 'utf-8-sig'
+master_doc = 'index'
+
+# General information about the project.
+project = u'Cabal'
+copyright = u'2016, Cabal Team'
+# N.B. version comes from ghc_config
+release = version  # The full version, including alpha/beta/rc tags.
+
+# Syntax highlighting
+highlight_language = 'haskell'
+#pygments_style = 'tango'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = ['.build', "*.gen.rst"]
+
+# -- Options for HTML output ---------------------------------------------
+
+# on_rtd is whether we are on readthedocs.org, this line of code grabbed from docs.readthedocs.org
+on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
+
+if not on_rtd:  # only import and set the theme if we're building docs locally
+    import sphinx_rtd_theme
+    html_theme = 'sphinx_rtd_theme'
+    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+html_title = "Cabal <release> User's Guide"
+html_short_title = "Cabal %s User's Guide" % release
+html_logo = 'images/Cabal-dark.png'
+html_static_path = ['images']
+# Convert quotes and dashes to typographically correct entities
+html_use_smartypants = 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
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'CabalUsersGuide'
+
+
+# -- Options for LaTeX output ---------------------------------------------
+
+latex_elements = {
+    'inputenc': '',
+    'utf8extra': '',
+    'preamble': '''
+\usepackage{fontspec}
+\usepackage{makeidx}
+\setsansfont{DejaVu Sans}
+\setromanfont{DejaVu Serif}
+\setmonofont{DejaVu Sans Mono}
+''',
+}
+
+# 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 = [
+  ('index', 'users_guide.tex', u'GHC Users Guide Documentation',
+   u'GHC Team', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+latex_logo = 'images/logo.pdf'
+
+# If true, show page references after internal links.
+latex_show_pagerefs = True
+
+
+# -- Options for manual page output ---------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    ('cabal', 'cabal', 'The Haskell Cabal', 'The Cabal Team', 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 = [
+  ('index', 'CabalUsersGuide', u'Cabal Users Guide',
+   u'Cabal Team', 'CabalUsersGuide', 'The Haskell Cabal.',
+   'Compilers'),
+]
+
+from sphinx import addnodes
+from docutils import nodes
+
+def parse_ghci_cmd(env, sig, signode):
+    name = sig.split(';')[0]
+    sig = sig.replace(';', '')
+    signode += addnodes.desc_name(name, sig)
+    return name
+
+def parse_flag(env, sig, signode):
+    import re
+    names = []
+    for i, flag in enumerate(sig.split(',')):
+        flag = flag.strip()
+        sep = '='
+        parts = flag.split('=')
+        if len(parts) == 1:
+            sep=' '
+            parts = flag.split()
+        if len(parts) == 0: continue
+
+        name = parts[0]
+        names.append(name)
+        sig = sep + ' '.join(parts[1:])
+        sig = re.sub(ur'<([-a-zA-Z ]+)>', ur'⟨\1⟩', sig)
+        if i > 0:
+            signode += addnodes.desc_name(', ', ', ')
+        signode += addnodes.desc_name(name, name)
+        if len(sig) > 0:
+            signode += addnodes.desc_addname(sig, sig)
+
+    return names[0]
+
+def setup(app):
+    from sphinx.util.docfields import Field, TypedField
+
+    increase_python_stack()
+
+    # the :ghci-cmd: directive used in ghci.rst
+    app.add_object_type('ghci-cmd', 'ghci-cmd',
+                        parse_node=parse_ghci_cmd,
+                        objname='GHCi command',
+                        indextemplate='pair: %s; GHCi command')
+
+    app.add_object_type('ghc-flag', 'ghc-flag',
+                        objname='GHC command-line option',
+                        parse_node=parse_flag,
+                        indextemplate='pair: %s; GHC option',
+                        doc_field_types=[
+                            Field('since', label='Introduced in GHC version', names=['since']),
+                            Field('default', label='Default value', names=['default']),
+                            Field('static')
+                        ])
+
+    app.add_object_type('rts-flag', 'rts-flag',
+                        objname='runtime system command-line option',
+                        parse_node=parse_flag,
+                        indextemplate='pair: %s; RTS option',
+                        doc_field_types=[
+                            Field('since', label='Introduced in GHC version', names=['since']),
+                        ])
+
+def increase_python_stack():
+    # Workaround sphinx-build recursion limit overflow:
+    # pickle.dump(doctree, f, pickle.HIGHEST_PROTOCOL)
+    #  RuntimeError: maximum recursion depth exceeded while pickling an object
+    #
+    # Default python allows recursion depth of 1000 calls.
+    sys.setrecursionlimit(10000)

doc/config-and-install.rst

+Configuration and Installing Packages
+=====================================
+
+.. toctree::
+   installing-packages

doc/developing-packages.rst

@@ -29,7 +29,7 @@ We can create both files manually or we can use ``cabal init`` to create
 them for us.
 
 Using "cabal init"
-~~~~~~~~~~~~~~~~~~
+------------------
 
 The ``cabal init`` command is interactive. It asks us a number of
 questions starting with the package name and version.
@@ -78,7 +78,7 @@ are able to build the package you will need to edit the file and add
 some build information about the library or executable.
 
 Editing the .cabal file
-~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------
 
 Load up the ``.cabal`` file in a text editor. The first part of the
 ``.cabal`` file has the package metadata and towards the end of the file
@@ -125,7 +125,7 @@ of the package too, but this is not required and the name is given
 explicitly.
 
 Modules included in the package
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------------
 
 For a library, ``cabal init`` looks in the project directory for files
 that look like Haskell modules and adds all the modules to the
@@ -141,7 +141,7 @@ contains your program's ``Main`` module. You will need to fill in the
 executable should be listed in the ``other-modules`` field.
 
 Modules imported from other packages
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------------------
 
 While your library or executable may include a number of modules, it
 almost certainly also imports a number of external modules from the
@@ -179,7 +179,7 @@ The last is just shorthand, for example ``base == 4.*`` means exactly
 the same thing as ``base >= 4 && < 5``.
 
 Building the package
-~~~~~~~~~~~~~~~~~~~~
+--------------------
 
 For simple packages that's it! We can now try configuring and building
 the package:
@@ -200,7 +200,7 @@ other packages. For executables it installs the program so that you can
 run it (though you may first need to adjust your system's ``$PATH``).
 
 Next steps
-~~~~~~~~~~
+----------
 
 What we have covered so far should be enough for very simple packages
 that you use on your own system.
@@ -219,7 +219,7 @@ understand a bit about packages in the Haskell world and the particular
 approach that Cabal takes.
 
 The point of packages
-~~~~~~~~~~~~~~~~~~~~~
+---------------------
 
 Packages are a mechanism for organising and distributing code. Packages
 are particularly suited for "programming in the large", that is building
@@ -251,7 +251,7 @@ related functionality. Thus the choice of module names in Haskell is
 still important, even when using packages.
 
 Package names and versions
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------------
 
 All packages have a name, e.g. "HUnit". Package names are assumed to be
 unique. Cabal package names may contain letters, numbers and hyphens,
@@ -283,7 +283,7 @@ identifies each installed package instance. Most of the time however,
 users need not be aware of this detail.
 
 Kinds of package: Cabal vs GHC vs system
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+----------------------------------------
 
 It can be slightly confusing at first because there are various
 different notions of package floating around. Fortunately the details
@@ -328,7 +328,7 @@ Operating system packages
     library dependencies, rather than packaging each library separately.
 
 Unit of distribution
-~~~~~~~~~~~~~~~~~~~~
+--------------------
 
 The Cabal package is the unit of distribution. What this means is that
 each Cabal package can be distributed on its own in source or binary
@@ -350,7 +350,7 @@ independently. Or to put it the other way round, if you want to
 distribute it as a single unit, then it should be a single package.
 
 Explicit dependencies and automatic package management
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------------------------------------
 
 Cabal takes the approach that all packages dependencies are specified
 explicitly and specified in a declarative way. The point is to enable
@@ -401,7 +401,7 @@ management means that Cabal's conditional dependencies system is a bit
 less flexible than with the "./configure" approach.
 
 Portability
-~~~~~~~~~~~
+-----------
 
 One of the purposes of Cabal is to make it easier to build packages on
 different platforms (operating systems and CPU architectures), with
@@ -704,7 +704,7 @@ The syntax of the value depends on the field. Field types include:
     ``LHC >=0.6 && <0.8``.
 
 Modules and preprocessors
-~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Haskell module names listed in the ``exposed-modules`` and
 ``other-modules`` fields may correspond to Haskell source files, i.e.
@@ -735,7 +735,7 @@ Some fields are marked as required. All others are optional, and unless
 otherwise specified have empty default values.
 
 Package properties
-~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^
 
 These fields may occur in the first top-level properties section and
 describe the package as a whole:
@@ -945,13 +945,13 @@ describe the package as a whole:
     parameters <#system-dependent-parameters>`__.
 
 Library
-~~~~~~~
+^^^^^^^
 
 The library section should contain the following fields:
 
-``exposed-modules:`` *identifier list* (required if this package
-contains a library)
+``exposed-modules:`` *identifier list* (required if this package contains a library)
     A list of modules added by this package.
+
 ``exposed:`` *boolean* (default: ``True``)
     Some Haskell compilers (notably GHC) support the notion of packages
     being "exposed" or "hidden" which means the modules they provide can
@@ -966,7 +966,7 @@ contains a library)
     that use a flat module namespace or where it is known that the
     exposed modules would clash with other common modules.
 
-``reexported-modules:`` *exportlist *
+``reexported-modules:`` *exportlist*
     Supported only in GHC 7.10 and later. A list of modules to
     *reexport* from this package. The syntax of this field is
     ``orig-pkg:Name as NewName`` to reexport module ``Name`` from
@@ -1050,7 +1050,7 @@ disambiguation purposes. Example:
     cabal repl bench:baz
 
 Freezing dependency versions
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+""""""""""""""""""""""""""""
 
 If a package is built in several different environments, such as a
 development environment, a staging environment and a production
@@ -1067,7 +1067,7 @@ The command writes the selected version for all dependencies to the
 the dependency versions specified in it.
 
 Generating dependency version bounds
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+""""""""""""""""""""""""""""""""""""
 
 Cabal also has the ability to suggest dependency version bounds that
 conform to `Package Versioning
@@ -1095,7 +1095,7 @@ For example, given the following dependencies specified in
     bar >= 1.1 && < 1.2
 
 Executables
-~~~~~~~~~~~
+^^^^^^^^^^^
 
 Executable sections (if present) describe executable programs contained
 in the package and must have an argument after the section label, which
@@ -1114,7 +1114,7 @@ information <#build-information>`__).
     ``hs-source-dirs``.
 
 Running executables
-^^^^^^^^^^^^^^^^^^^
+"""""""""""""""""""
 
 You can have Cabal build and run your executables by using the ``run``
 command:
@@ -1131,7 +1131,7 @@ omitted. See the output of ``cabal help run`` for a list of options you
 can pass to ``cabal run``.
 
 Test suites
-~~~~~~~~~~~
+^^^^^^^^^^^
 
 Test suite sections (if present) describe package test suites and must
 have an argument after the section label, which defines the name of the
@@ -1156,8 +1156,7 @@ provide human-readable log information through the standard output and
 error channels. The ``exitcode-stdio-1.0`` type requires the ``main-is``
 field.
 
-``main-is:`` *filename* (required: ``exitcode-stdio-1.0``, disallowed:
-``detailed-0.9``)
+``main-is:`` *filename* (required: ``exitcode-stdio-1.0``, disallowed: ``detailed-0.9``)
     The name of the ``.hs`` or ``.lhs`` file containing the ``Main``
     module. Note that it is the ``.hs`` filename that must be listed,
     even if that file is generated using a preprocessor. The source file
@@ -1175,12 +1174,11 @@ inspect a test suite's results case by case, producing detailed human-
 and machine-readable log files. The ``detailed-0.9`` interface requires
 the ``test-module`` field.
 
-``test-module:`` *identifier* (required: ``detailed-0.9``, disallowed:
-``exitcode-stdio-1.0``)
+``test-module:`` *identifier* (required: ``detailed-0.9``, disallowed: ``exitcode-stdio-1.0``)
     The module exporting the ``tests`` symbol.
 
 Example: Package using ``exitcode-stdio-1.0`` interface
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+"""""""""""""""""""""""""""""""""""""""""""""""""""""""
 
 The example package description and executable source file below
 demonstrate the use of the ``exitcode-stdio-1.0`` interface.
@@ -1213,7 +1211,7 @@ test-foo.hs:
         exitFailure
 
 Example: Package using ``detailed-0.9`` interface
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+"""""""""""""""""""""""""""""""""""""""""""""""""
 
 The example package description and test module source file below
 demonstrate the use of the ``detailed-0.9`` interface. The test module
@@ -1223,7 +1221,7 @@ be provided by the library that provides the testing facility.
 
 bar.cabal:
 
-::
+.. code-block:: none
 
     Name:           bar
     Version:        1.0
@@ -1236,6 +1234,7 @@ bar.cabal:
         test-module: Bar
         build-depends: base, Cabal >= 1.9.2
 
+
 Bar.hs:
 
 ::
@@ -1263,7 +1262,7 @@ Bar.hs:
             }
 
 Running test suites
-^^^^^^^^^^^^^^^^^^^
+"""""""""""""""""""
 
 You can have Cabal run your test suites using its built-in test runner:
 
@@ -1277,7 +1276,7 @@ See the output of ``cabal help test`` for a list of options you can pass
 to ``cabal test``.
 
 Benchmarks
-~~~~~~~~~~
+^^^^^^^^^^
 
 Benchmark sections (if present) describe benchmarks contained in the
 package and must have an argument after the section label, which defines
@@ -1309,7 +1308,7 @@ standard output and error channels.
     of an executable section.
 
 Example: Package using ``exitcode-stdio-1.0`` interface
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+"""""""""""""""""""""""""""""""""""""""""""""""""""""""
 
 The example package description and executable source file below
 demonstrate the use of the ``exitcode-stdio-1.0`` interface.
@@ -1349,7 +1348,7 @@ bench-foo.hs:
         putStrLn $ "fib 20 took " ++ show (diffUTCTime end start)
 
 Running benchmarks
-^^^^^^^^^^^^^^^^^^
+""""""""""""""""""
 
 You can have Cabal run your benchmark using its built-in benchmark
 runner:
@@ -1364,7 +1363,7 @@ See the output of ``cabal help bench`` for a list of options you can
 pass to ``cabal bench``.
 
 Build information
-~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^
 
 The following fields may be optionally present in a library, executable,
 test suite or benchmark section, and give information for the building
@@ -1630,7 +1629,7 @@ system-dependent values for these fields.
     This entry is ignored on all other platforms.
 
 Configurations
-~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^
 
 Library and executable sections may include conditional blocks, which
 test for various system parameters and configuration flags. The flags
@@ -1639,7 +1638,7 @@ certain feature, that can be switched on or off by the package user.
 Here is an example package description file using configurations:
 
 Example: A package containing a library and executable programs
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 
 ::
 
@@ -1686,7 +1685,7 @@ Example: A package containing a library and executable programs
         GHC-Options: -DDEBUG
 
 Layout
-^^^^^^
+""""""
 
 Flags, conditionals, library and executable sections use layout to
 indicate structure. This is very similar to the Haskell layout rule.
@@ -1700,7 +1699,7 @@ matter, though different fields within a block must be on different
 lines. Here is a bit of the above example again, using braces:
 
 Example: Using explicit braces rather than indentation for layout
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 
 ::
 
@@ -1732,7 +1731,7 @@ Example: Using explicit braces rather than indentation for layout
     }
 
 Configuration Flags
-^^^^^^^^^^^^^^^^^^^
+"""""""""""""""""""
 
 A flag section takes the flag name as an argument and may contain the
 following fields.
@@ -1780,7 +1779,7 @@ or
 Note that the ``if`` and the condition have to be all on the same line.
 
 Conditions
-^^^^^^^^^^
+""""""""""
 
 Conditions can be formed using boolean tests and the boolean operators
 ``||`` (disjunction / logical "or"), ``&&`` (conjunction / logical
@@ -1836,7 +1835,7 @@ The following tests are currently supported.
     Constant value false.
 
 Resolution of Conditions and Flags
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+""""""""""""""""""""""""""""""""""
 
 If a package descriptions specifies configuration flags the package user
 can `control these in several
@@ -1872,7 +1871,7 @@ optimizations applied internally, but the overall complexity remains
 unchanged.
 
 Meaning of field values when using conditionals
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 During the configuration phase, a flag assignment is chosen, all
 conditionals are evaluated, and the package description is combined into
@@ -1918,7 +1917,7 @@ and outside then they are combined using the following rules.
          Main-is: Main.hs
 
 Source Repositories
-~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^
 
 It is often useful to be able to specify a source revision control
 repository for a package. Cabal lets you specifying this information in
@@ -2025,7 +2024,7 @@ The exact fields are as follows:
     root directory of the repository.
 
 Downloading a package's source
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The ``cabal get`` command allows to access a package's source code -
 either by unpacking a tarball downloaded from Hackage (the default) or
@@ -2156,7 +2155,7 @@ the configured data directory for ``pretty-show`` is controlled with the
 ``pretty_show_datadir`` environment variable.
 
 Accessing the package version
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The aforementioned auto generated ``Paths_``\ *pkgname* module also
 exports the constant ``version ::``

doc/index.rst

-**Version: 1.25.0.0**
 
-Cabal is the standard package system for
-`Haskell <http://www.haskell.org/>`__ software. It helps people to
-configure, build and install Haskell software and to distribute it
-easily to other users and developers.
+Welcome to the Cabal User Guide
+===============================
 
-There is a command line tool called ``cabal`` for working with Cabal
-packages. It helps with installing existing packages and also helps
-people developing their own packages. It can be used to work with local
-packages or to install packages from online package archives, including
-automatically installing dependencies. By default it is configured to
-use `Hackage <http://hackage.haskell.org/>`__ which is Haskell's central
-package archive that contains thousands of libraries and applications in
-the Cabal package format.
+.. toctree::
+   :maxdepth: 2
+   :numbered:
 
-Contents
-========
-
--  `Introduction <#introduction>`__
-
-   -  `What's in a package <#whats-in-a-package>`__
-   -  `A tool for working with
-      packages <#a-tool-for-working-with-packages>`__
-
--  `Building, installing and managing
-   packages <installing-packages.html>`__
--  `Creating packages <developing-packages.html>`__
--  `Reporting bugs and
-   deficiencies <misc.html#reporting-bugs-and-deficiencies>`__
--  `Stability of Cabal
-   interfaces <misc.html#stability-of-cabal-interfaces>`__
-
-Introduction
-============
-
-Cabal is a package system for Haskell software. The point of a package
-system is to enable software developers and users to easily distribute,
-use and reuse software. A package