Commit e84bf2d3 authored by Edward Z. Yang's avatar Edward Z. Yang Committed by GitHub
Browse files

Merge pull request #3780 from linearray/pr/sphinx-doc

Cabal documentation converted to RST/Sphinx
parents 120547e0 2573a3a8
......@@ -23,9 +23,11 @@ build-type: Simple
extra-source-files:
README.md tests/README.md changelog
doc/Cabal.css doc/developing-packages.markdown doc/index.markdown
doc/installing-packages.markdown
doc/misc.markdown
doc/bugs-and-stability.rst doc/concepts-and-development.rst
doc/conf.py doc/config-and-install.rst doc/developing-packages.rst
doc/images/Cabal-dark.png doc/index.rst doc/installing-packages.rst
doc/intro.rst doc/misc.rst doc/nix-local-build-overview.rst
doc/nix-local-build.rst doc/README.md
-- Generated with 'misc/gen-extra-source-files.sh'
-- Do NOT edit this section manually; instead, run the script.
......
body {
max-width: 18cm;
}
div {
font-family: sans-serif;
color: black;
background: white
}
h1, h2, h3, h4, h5, h6, p.title { color: #005A9C }
h1 { font: 170% sans-serif }
h2 { font: 140% sans-serif }
h3 { font: 120% sans-serif }
h4 { font: bold 100% sans-serif }
h5 { font: italic 100% sans-serif }
h6 { font: small-caps 100% sans-serif }
pre {
font-family: monospace;
border-width: 1px;
border-style: solid;
padding: 0.3em
}
pre.screen { color: #006400 }
pre.programlisting { color: maroon }
div.example {
margin: 1ex 0em;
border: solid #412e25 1px;
padding: 0ex 0.4em
}
div.example, div.example-contents {
background-color: #fffcf5
}
a:link { color: #0000C8 }
a:hover { background: #FFFFA8 }
a:active { color: #D00000 }
a:visited { color: #680098 }
h1 a:link, h2 a:link, h3 a:link, h4 a:link, h5 a:link, h6 a:link,
h1 a:visited, h2 a:visited, h3 a:visited, h4 a:visited, h5 a:visited, h6 a:visited {
color: #005A9C;
text-decoration: none
}
Cabal documentation
===================
### Where to read it
These docs will be built and deployed whenever a release is made,
and can be read at: https://www.haskell.org/cabal/users-guide/
In addition, the docs are taken directly from git and hosted at:
http://cabal.readthedocs.io/
### 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
### Caveats, for newcomers to RST from MD
RST does not allow you to skip section levels when nesting, like MD
does.
So, you cannot have
```
Section heading
===============
Some unimportant block
""""""""""""""""""""""
```
instead you need to observe order and either promote your block:
```
Section heading
===============
Some not quite so important block
---------------------------------
```
or introduce more subsections:
```
Section heading
===============
Subsection
----------
Subsubsection
^^^^^^^^^^^^^
Some unimportant block
""""""""""""""""""""""
```
* RST simply parses a file and interpretes headings to indicate the
start of a new block,
* at the level implied by the header's *adornment*, if the adornment was
previously encountered in this file,
* at one level deeper than the previous block, otherwise.
This means that a lot of confusion can arise when people use
different adornments to signify the same depth in different files.
To eliminate this confusion, please stick to the adornment order
recommended by the Sphinx team:
```
####
Part
####
*******
Chapter
*******
Section
=======
Subsection
----------
Subsubsection
^^^^^^^^^^^^^
Paragraph
"""""""""
```
* The Read-The-Docs stylesheet does not support multiple top-level
sections in a file that is linked to from the top-most TOC (in
`index.rst`). It will mess up the sidebar.
E.g. you cannot link to a `cabal.rst` with sections "Introduction",
"Using Cabal", "Epilogue" from `index.rst`.
One solution is to have a single section, e.g. "All About Cabal", in
`cabal.rst` and make the other blocks subsections of that.
Another solution is to link via an indirection, e.g. create
`all-about-cabal.rst`, where you include `cabal.rst` using the
`.. toctree::` command and then link to `all-about-cabal.rst` from
`index.rst`.
This will effectively "push down" all blocks by one layer and solve
the problem without having to change `cabal.rst`.
Reporting Bugs and Stability of Cabal Interfaces
================================================
.. toctree::
misc
Package Concepts and Development
================================
.. toctree::
:maxdepth: 2
developing-packages
# -*- 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)
Configuration and Installing Packages
=====================================
.. toctree::
installing-packages
Welcome to the Cabal User Guide
===============================
.. toctree::
:maxdepth: 2
:numbered:
intro
config-and-install
concepts-and-development
bugs-and-stability
nix-local-build-overview
This diff is collapsed.
This diff is collapsed.
% Cabal User Guide
**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.
Cabal is the standard package system for [Haskell] software. It helps
people to configure, build and install Haskell software and to
distribute it easily to other users and developers.
There is a command line tool called `cabal` for working with Cabal
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] which is Haskell's central package archive that contains
thousands of libraries and applications in the Cabal package format.
# Contents #
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.
* [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 #
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,
......@@ -32,13 +22,13 @@ to get their software into the hands of users. Equally importantly, it
makes it easier for software developers to be able to reuse software
components written by other developers.
Packaging systems deal with packages and with Cabal we call them _Cabal
packages_. The Cabal package is the unit of distribution. Every Cabal
Packaging systems deal with packages and with Cabal we call them *Cabal
packages*. The Cabal package is the unit of distribution. Every Cabal
package has a name and a version number which are used to identify the
package, e.g. `filepath-1.0`.
package, e.g. ``filepath-1.0``.
Cabal packages can depend on other Cabal packages. There are tools
to enable automated package management. This means it is possible for
Cabal packages can depend on other Cabal packages. There are tools to
enable automated package management. This means it is possible for
developers and users to install a package plus all of the other Cabal
packages that it depends on. It also means that it is practical to make
very modular systems using lots of packages that reuse code written by
......@@ -50,27 +40,28 @@ package format is designed to make it possible to translate into other
formats, including binary packages for various systems.
When distributed, Cabal packages use the standard compressed tarball
format, with the file extension `.tar.gz`, e.g. `filepath-1.0.tar.gz`.
format, with the file extension ``.tar.gz``, e.g.
``filepath-1.0.tar.gz``.
Note that packages are not part of the Haskell language, rather they
are a feature provided by the combination of Cabal and GHC (and several
Note that packages are not part of the Haskell language, rather they are
a feature provided by the combination of Cabal and GHC (and several
other Haskell implementations).
A tool for working with packages
--------------------------------
## A tool for working with packages ##
There is a command line tool, called "`cabal`", that users and developers
can use to build and install Cabal packages. It can be used for both
local packages and for packages available remotely over the network. It
can automatically install Cabal packages plus any other Cabal packages
they depend on.
There is a command line tool, called "``cabal``", that users and
developers can use to build and install Cabal packages. It can be used
for both local packages and for packages available remotely over the
network. It can automatically install Cabal packages plus any other
Cabal packages they depend on.
Developers can use the tool with packages in local directories, e.g.
~~~~~~~~~~~~~~~~
cd foo/
cabal install
~~~~~~~~~~~~~~~~
::
cd foo/
cabal install
While working on a package in a local directory, developers can run the
individual steps to configure and build, and also generate documentation
......@@ -78,79 +69,85 @@ and run test suites and benchmarks.
It is also possible to install several local packages at once, e.g.
~~~~~~~~~~~~~~~~
cabal install foo/ bar/
~~~~~~~~~~~~~~~~
::
cabal install foo/ bar/
Developers and users can use the tool to install packages from remote
Cabal package archives. By default, the `cabal` tool is configured to
use the central Haskell package archive called [Hackage] but it
is possible to use it with any other suitable archive.
Cabal package archives. By default, the ``cabal`` tool is configured to
use the central Haskell package archive called
`Hackage <http://hackage.haskell.org/>`__ but it is possible to use it
with any other suitable archive.
~~~~~~~~~~~~~~~~
cabal install xmonad
~~~~~~~~~~~~~~~~
::
This will install the `xmonad` package plus all of its dependencies.
cabal install xmonad
This will install the ``xmonad`` package plus all of its dependencies.
In addition to packages that have been published in an archive,
developers can install packages from local or remote tarball files,
for example
developers can install packages from local or remote tarball files, for
example
::
~~~~~~~~~~~~~~~~
cabal install foo-1.0.tar.gz
cabal install http://example.com/foo-1.0.tar.gz
~~~~~~~~~~~~~~~~
cabal install foo-1.0.tar.gz
cabal install http://example.com/foo-1.0.tar.gz
Cabal provides a number of ways for a user to customise how and where a
package is installed. They can decide where a package will be installed,
which Haskell implementation to use and whether to build optimised code
or build with the ability to profile code. It is not expected that users
will have to modify any of the information in the `.cabal` file.
will have to modify any of the information in the ``.cabal`` file.
For full details, see the section on [building and installing
packages](installing-packages.html).
For full details, see the section on `building and installing
packages <installing-packages.html>`__.
Note that `cabal` is not the only tool for working with Cabal packages.
Due to the standardised format and a library for reading `.cabal` files,
there are several other special-purpose tools.
Note that ``cabal`` is not the only tool for working with Cabal
packages. Due to the standardised format and a library for reading
``.cabal`` files, there are several other special-purpose tools.
## What's in a package ##
What's in a package
-------------------
A Cabal package consists of:
* Haskell software, including libraries, executables and tests
* metadata about the package in a standard human and machine
readable format (the "`.cabal`" file)
* a standard interface to build the package (the "`Setup.hs`" file)
- Haskell software, including libraries, executables and tests
- metadata about the package in a standard human and machine readable
format (the "``.cabal``" file)
- a standard interface to build the package (the "``Setup.hs``" file)
The `.cabal` file contains information about the package, supplied by
the package author. In particular it lists the other Cabal packages
that the package depends on.
The ``.cabal`` file contains information about the package, supplied by
the package author. In particular it lists the other Cabal packages that
the package depends on.
For full details on what goes in the `.cabal` and `Setup.hs` files, and
for all the other features provided by the build system, see the section
on [developing packages](developing-packages.html).
For full details on what goes in the ``.cabal`` and ``Setup.hs`` files,
and for all the other features provided by the build system, see the
section on `developing packages <developing-packages.html>`__.
## Cabal featureset ##
Cabal featureset
----------------
Cabal and its associated tools and websites covers:
* a software build system
* software configuration
* packaging for distribution
* automated package management
* natively using the `cabal` command line tool; or
* by translation into native package formats such as RPM or deb
* web and local Cabal package archives
* central Hackage website with 1000's of Cabal packages
- a software build system
- software configuration
- packaging for distribution
- automated package management
- natively using the ``cabal`` command line tool; or
- by translation into native package formats such as RPM or deb
- web and local Cabal package archives
- central Hackage website with 1000's of Cabal packages
Some parts of the system can be used without others. In particular the
built-in build system for simple packages is optional: it is possible
to use custom build systems.
built-in build system for simple packages is optional: it is possible to
use custom build systems.