Purnank Ghumalia avatar Purnank Ghumalia committed ec2a319 Merge

Merged birkenfeld/sphinx into default

Comments (0)

Files changed (333)

+language: python
+python:
+  - "2.7"
+  - "3.3"
+script: make test
+install:
+  - python setup.py -q install
 * Charles Duffy -- original graphviz extension
 * Kevin Dunn -- MathJax extension
 * Josip Dzolonga -- coverage builder
+* Hernan Grecco -- search improvements
 * Horst Gutmann -- internationalization support
 * Martin Hans -- autodoc improvements
 * Doug Hellmann -- graphviz improvements
 Release 1.2 (in development)
 ============================
 
+* Fix text builder did not respect wide/fullwidth characters:
+  title underline width, table layout width and text wrap width.
+
+* #1062: sphinx.ext.autodoc use __init__ method signature for class signature.
+
+* PR#111: Respect add_autodoc_attrgetter() even when inherited-members is set.
+  Thanks to A. Jesse Jiryu Davis.
+
+* #1090: Fix gettext does not extract glossary terms.
+
+* #1070: Avoid un-pickling issues when running Python 3 and the saved
+  environment was created under Python 2.
+
+* #1069: Fixed error caused when autodoc would try to format signatures of
+  "partial" functions without keyword arguments (patch by Artur Gaspar).
+
+* The :confval:`latex_documents`, :confval:`texinfo_documents`, and
+  :confval:`man_pages` configuration values will be set to default values based
+  on the :confval:`master_doc` if not explicitly set in :file:`conf.py`.
+  Previously, if these values were not set, no output would be genereted by
+  their respective builders.
+
+* The :rst:dir:`toctree` directive and the ``toctree()`` template function now
+  have an ``includehidden`` option that includes hidden toctree entries (bugs
+  #790 and #1047). A bug in the ``maxdepth`` option for the ``toctree()``
+  template function has been fixed (bug #1046).
+
+* PR#99: Strip down seealso directives to normal admonitions.  This removes
+  their unusual CSS classes (admonition-see-also), inconsistent LaTeX
+  admonition title ("See Also" instead of "See also"), and spurious indentation
+  in the text builder.
+
+* sphinx-build now has a verbose option :option:`-v` which can be
+  repeated for greater effect.  A single occurrance provides a
+  slightly more verbose output than normal.  Two or more occurrences
+  of this option provides more detailed output which may be useful for
+  debugging.
+
+* sphinx-build now provides more specific error messages when called with
+  invalid options or arguments.
+
+* sphinx-build now supports the standard :option:`--help` and
+  :option:`--version` options.
+
+* #869: sphinx-build now has the option :option:`-T` for printing the full
+  traceback after an unhandled exception.
+
+* #976: Fix gettext does not extract index entries.
+
+* #940: Fix gettext does not extract figure caption.
+
+* #1067: Improve the ordering of the JavaScript search results: matches in titles
+  come before matches in full text, and object results are better categorized.
+  Also implement a pluggable search scorer.
+
+* Fix text writer can not handle visit_legend for figure directive contents.
+
+* PR#72: #975: Fix gettext does not extract definition terms before docutils 0.10.0
+
+* PR#25: In inheritance diagrams, the first line of the class docstring
+  is now the tooltip for the class.
+
+* PR#47: Added :mod:`sphinx.ext.linkcode` extension.
+
+* PR#75: Added ``--follow-links`` option to sphinx-apidoc.
+
 * PR#45: The linkcheck builder now checks ``#anchor``\ s for existence.
 
 * PR#28: Added Hungarian translation.
 
 * PR#52: ``special_members`` flag to autodoc now behaves like ``members``.
 
+* #955: Fix i18n transformation.
+
+* Handle duplicate domain indices in texinfo.
+
+* PR#74: Fix some Russian translation.
+
+* PR#97: Fix footnote handling in translated documents.
+
 * Update to jQuery 1.7.1 and Underscore.js 1.3.1.
 
-
-Release 1.1.4 (in development)
-==============================
+* #1055: Fix web support with relative path to source directory.
+
+* #1053: The "rightsidebar" and "collapsiblesidebar" HTML theme options now work together.
+
+* #1015: Stop overriding jQuery contains() in the JavaScript.
+
+* #1028: Fix line block output in the text builder.
+
+* #1018: Fix "container" directive handling in the text builder.
+
+* #1012: Update Estonian translation.
+
+* #1010: Make pngmath images transparent by default; IE7+ should handle it.
+
+* #440: Fix coarse timestamp resolution in some filesystem generate wrong outdated file-list.
+
+* #1008: Fix test failures with Python 3.3.
+
+* #1029: Fix intersphinx_mapping values are not stable if mapping have plural key/value set with Python 3.3.
+
+* #920: Rescue PIL packaging issue that allow import Image without PIL namespace. Thanks to Marc Schlaich.
+
+* #1024: Improve Makefile/make.bat error message if Sphinx is not found. Thanks to anatoly techtonik.
+
+* #1037: Fix typos in Polish translation. Thanks to Jakub Wilk.
+
+* #1038: Fix cpp domain parser fails to parse C+11 "static constexpr" declarations. Thanks to Jakub Wilk.
+
+* #1043: Fix sphinx-quickstart asks again and again Y|N because input() return value with extra '\r' on Python-3.2.0 + Windows. Thanks to Régis Décamps.
+
+* #1041: Fix cpp domain parser fails to parse a const type with a modifier.
+
+* #958: Do not preserve ``environment.pickle`` after a failed build.
+
+* PR#88: Added the "Sphinx Developer's Guide" (:file:`doc/devguide.rst`)
+  which outlines the basic development process of the Sphinx project.
+
+* Added the Docutils-native XML and pseudo-XML builders.  See
+  :class:`XMLBuilder` and :class:`PseudoXMLBuilder`.
 
 
 Release 1.1.3 (Mar 10, 2012)
 This is an (incomplete) alphabetic list of projects that use Sphinx or
 are experimenting with using it for their documentation.  If you like to
 be included, please mail to `the Google group
-<http://groups.google.com/group/sphinx-dev>`_.
+<http://groups.google.com/group/sphinx-users>`_.
 
 I've grouped the list into sections to make it easier to find
 interesting examples.
 * Chaco: http://code.enthought.com/projects/chaco/docs/html/
 * Djagios: http://djagios.org/
 * GetFEM++: http://home.gna.org/getfem/
+* Google or-tools: https://or-tools.googlecode.com/svn/trunk/documentation/user_manual/index.html
 * GPAW: https://wiki.fysik.dtu.dk/gpaw/
 * Grok: http://grok.zope.org/doc/current/
 * IFM: http://fluffybunny.memebot.com/ifm-docs/index.html
   http://www.tango-controls.org/static/PyTango/latest/doc/html/index.html
 * Reteisi: http://www.reteisi.org/contents.html
 * Satchmo: http://www.satchmoproject.com/docs/dev/
-* Sphinx: http://sphinx.pocoo.org/
+* Sphinx: http://sphinx-doc.org/
 * Sqlkit: http://sqlkit.argolinux.org/
 * Tau: http://www.tango-controls.org/static/tau/latest/doc/html/index.html
 * Total Open Station: http://tops.berlios.de/
+* Turbulenz: http://docs.turbulenz.com/
 * WebFaction: http://docs.webfaction.com/
 
 
   (agogo)
 * Sylli: http://sylli.sourceforge.net/ (nature)
 * libLAS: http://liblas.org/ (nature)
+* Valence: http://docs.valence.desire2learn.com/ (haiku)
 
 
 Documentation using a custom theme/integrated in a site
 
 * Blender: http://www.blender.org/documentation/250PythonDoc/
 * Blinker: http://discorporate.us/projects/Blinker/docs/
-* Classy: classy: http://classy.pocoo.org/
+* Classy: http://classy.pocoo.org/
+* DEAP: http://deap.gel.ulaval.ca/doc/0.8/index.html
 * Django: http://docs.djangoproject.com/
 * e-cidadania: http://e-cidadania.readthedocs.org/en/latest/
 * Flask: http://flask.pocoo.org/docs/
 * Gameduino: http://excamera.com/sphinx/gameduino/
 * GeoServer: http://docs.geoserver.org/
 * Glashammer: http://glashammer.org/
+* Istihza (Turkish Python documentation project): http://www.istihza.com/py2/icindekiler_python.html
+* MathJax: http://docs.mathjax.org/en/latest/
 * MirrorBrain: http://mirrorbrain.org/docs/
 * nose: http://somethingaboutorange.com/mrl/projects/nose/
 * ObjectListView: http://objectlistview.sourceforge.net/python
 * Open ERP: http://doc.openerp.com/
+* OpenCV: http://docs.opencv.org/
 * OpenLayers: http://docs.openlayers.org/
 * PyEphem: http://rhodesmill.org/pyephem/
 * German Plone 4.0 user manual: http://www.hasecke.com/plone-benutzerhandbuch/4.0/
+* PSI4: http://sirius.chem.vt.edu/psi4manual/latest/index.html
 * Pylons: http://pylonshq.com/docs/en/0.9.7/
 * PyMOTW: http://www.doughellmann.com/PyMOTW/
 * pypol: http://pypol.altervista.org/ (celery)
 * SQLAlchemy: http://www.sqlalchemy.org/docs/
 * tinyTiM: http://tinytim.sourceforge.net/docs/2.0/
 * tipfy: http://www.tipfy.org/docs/
+* Ubuntu packaging guide: http://developer.ubuntu.com/packaging/html/
 * Werkzeug: http://werkzeug.pocoo.org/docs/
 * WFront: http://discorporate.us/projects/WFront/
 
 License for Sphinx
 ==================
 
-Copyright (c) 2007-2011 by the Sphinx team (see AUTHORS file).
+Copyright (c) 2007-2013 by the Sphinx team (see AUTHORS file).
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without
 
 Then, direct your browser to ``_build/html/index.html``.
 
-Or read them online at <http://sphinx.pocoo.org/>.
+Or read them online at <http://sphinx-doc.org/>.
 
 
 Testing

distribute_setup.py

 This file can also be run as a script to install or upgrade setuptools.
 """
 import os
+import shutil
 import sys
 import time
 import fnmatch
 import tempfile
 import tarfile
+import optparse
+
 from distutils import log
 
 try:
             args = [quote(arg) for arg in args]
         return os.spawnl(os.P_WAIT, sys.executable, *args) == 0
 
-DEFAULT_VERSION = "0.6.13"
+DEFAULT_VERSION = "0.6.30"
 DEFAULT_URL = "http://pypi.python.org/packages/source/d/distribute/"
 SETUPTOOLS_FAKED_VERSION = "0.6c11"
 
 """ % SETUPTOOLS_FAKED_VERSION
 
 
-def _install(tarball):
+def _install(tarball, install_args=()):
     # extracting the tarball
     tmpdir = tempfile.mkdtemp()
     log.warn('Extracting in %s', tmpdir)
 
         # installing
         log.warn('Installing Distribute')
-        if not _python_cmd('setup.py', 'install'):
+        if not _python_cmd('setup.py', 'install', *install_args):
             log.warn('Something went wrong during the installation.')
             log.warn('See the error message above.')
+            # exitcode will be 2
+            return 2
     finally:
         os.chdir(old_wd)
+        shutil.rmtree(tmpdir)
 
 
 def _build_egg(egg, tarball, to_dir):
 
     finally:
         os.chdir(old_wd)
+        shutil.rmtree(tmpdir)
     # returning the result
     log.warn(egg)
     if not os.path.exists(egg):
         except ImportError:
             return _do_download(version, download_base, to_dir, download_delay)
         try:
-            pkg_resources.require("distribute>="+version)
+            pkg_resources.require("distribute>=" + version)
             return
         except pkg_resources.VersionConflict:
             e = sys.exc_info()[1]
         if not no_fake:
             _create_fake_setuptools_pkg_info(to_dir)
 
+
 def download_setuptools(version=DEFAULT_VERSION, download_base=DEFAULT_URL,
                         to_dir=os.curdir, delay=15):
     """Download distribute from a specified location and return its filename
                 dst.close()
     return os.path.realpath(saveto)
 
+
 def _no_sandbox(function):
     def __no_sandbox(*args, **kw):
         try:
 
     return __no_sandbox
 
+
 def _patch_file(path, content):
     """Will backup the file then patch it"""
     existing_content = open(path).read()
 
 _patch_file = _no_sandbox(_patch_file)
 
+
 def _same_content(path, content):
     return open(path).read() == content
 
+
 def _rename_path(path):
     new_name = path + '.OLD.%s' % time.time()
-    log.warn('Renaming %s into %s', path, new_name)
+    log.warn('Renaming %s to %s', path, new_name)
     os.rename(path, new_name)
     return new_name
 
+
 def _remove_flat_installation(placeholder):
     if not os.path.isdir(placeholder):
         log.warn('Unkown installation at %s', placeholder)
         log.warn('Could not locate setuptools*.egg-info')
         return
 
-    log.warn('Removing elements out of the way...')
+    log.warn('Moving elements out of the way...')
     pkg_info = os.path.join(placeholder, file)
     if os.path.isdir(pkg_info):
         patched = _patch_egg_dir(pkg_info)
 
 _remove_flat_installation = _no_sandbox(_remove_flat_installation)
 
+
 def _after_install(dist):
     log.warn('After install bootstrap.')
     placeholder = dist.get_command_obj('install').install_purelib
     _create_fake_setuptools_pkg_info(placeholder)
 
+
 def _create_fake_setuptools_pkg_info(placeholder):
     if not placeholder or not os.path.exists(placeholder):
         log.warn('Could not find the install location')
         return
 
     log.warn('Creating %s', pkg_info)
-    f = open(pkg_info, 'w')
+    try:
+        f = open(pkg_info, 'w')
+    except EnvironmentError:
+        log.warn("Don't have permissions to write %s, skipping", pkg_info)
+        return
     try:
         f.write(SETUPTOOLS_PKG_INFO)
     finally:
     finally:
         f.close()
 
-_create_fake_setuptools_pkg_info = _no_sandbox(_create_fake_setuptools_pkg_info)
+_create_fake_setuptools_pkg_info = _no_sandbox(
+    _create_fake_setuptools_pkg_info
+)
+
 
 def _patch_egg_dir(path):
     # let's check if it's already patched
 
 _patch_egg_dir = _no_sandbox(_patch_egg_dir)
 
+
 def _before_install():
     log.warn('Before install bootstrap.')
     _fake_setuptools()
 def _under_prefix(location):
     if 'install' not in sys.argv:
         return True
-    args = sys.argv[sys.argv.index('install')+1:]
+    args = sys.argv[sys.argv.index('install') + 1:]
     for index, arg in enumerate(args):
         for option in ('--root', '--prefix'):
             if arg.startswith('%s=' % option):
                 return location.startswith(top_dir)
             elif arg == option:
                 if len(args) > index:
-                    top_dir = args[index+1]
+                    top_dir = args[index + 1]
                     return location.startswith(top_dir)
         if arg == '--user' and USER_SITE is not None:
             return location.startswith(USER_SITE)
         return
     ws = pkg_resources.working_set
     try:
-        setuptools_dist = ws.find(pkg_resources.Requirement.parse('setuptools',
-                                  replacement=False))
+        setuptools_dist = ws.find(
+            pkg_resources.Requirement.parse('setuptools', replacement=False)
+            )
     except TypeError:
         # old distribute API
-        setuptools_dist = ws.find(pkg_resources.Requirement.parse('setuptools'))
+        setuptools_dist = ws.find(
+            pkg_resources.Requirement.parse('setuptools')
+        )
 
     if setuptools_dist is None:
         log.warn('No setuptools distribution found')
         res = _patch_egg_dir(setuptools_location)
         if not res:
             return
-    log.warn('Patched done.')
+    log.warn('Patching complete.')
     _relaunch()
 
 
     log.warn('Relaunching...')
     # we have to relaunch the process
     # pip marker to avoid a relaunch bug
-    if sys.argv[:3] == ['-c', 'install', '--single-version-externally-managed']:
+    _cmd1 = ['-c', 'install', '--single-version-externally-managed']
+    _cmd2 = ['-c', 'install', '--record']
+    if sys.argv[:3] == _cmd1 or sys.argv[:3] == _cmd2:
         sys.argv[0] = 'setup.py'
     args = [sys.executable] + sys.argv
     sys.exit(subprocess.call(args))
             # Extract directories with a safe mode.
             directories.append(tarinfo)
             tarinfo = copy.copy(tarinfo)
-            tarinfo.mode = 448 # decimal for oct 0700
+            tarinfo.mode = 448  # decimal for oct 0700
         self.extract(tarinfo, path)
 
     # Reverse sort directories.
                 self._dbg(1, "tarfile: %s" % e)
 
 
-def main(argv, version=DEFAULT_VERSION):
+def _build_install_args(options):
+    """
+    Build the arguments to 'python setup.py install' on the distribute package
+    """
+    install_args = []
+    if options.user_install:
+        if sys.version_info < (2, 6):
+            log.warn("--user requires Python 2.6 or later")
+            raise SystemExit(1)
+        install_args.append('--user')
+    return install_args
+
+def _parse_args():
+    """
+    Parse the command line for options
+    """
+    parser = optparse.OptionParser()
+    parser.add_option(
+        '--user', dest='user_install', action='store_true', default=False,
+        help='install in user site package (requires Python 2.6 or later)')
+    parser.add_option(
+        '--download-base', dest='download_base', metavar="URL",
+        default=DEFAULT_URL,
+        help='alternative URL from where to download the distribute package')
+    options, args = parser.parse_args()
+    # positional arguments are ignored
+    return options
+
+def main(version=DEFAULT_VERSION):
     """Install or upgrade setuptools and EasyInstall"""
-    tarball = download_setuptools()
-    _install(tarball)
-
+    options = _parse_args()
+    tarball = download_setuptools(download_base=options.download_base)
+    return _install(tarball, _build_install_args(options))
 
 if __name__ == '__main__':
-    main(sys.argv[1:])
+    sys.exit(main())
 I18NSPHINXOPTS   = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(O) .
 
 .PHONY: help clean html dirhtml singlehtml text man pickle json htmlhelp \
-	qthelp devhelp epub latex latexpdf changes linkcheck doctest
+	qthelp devhelp epub latex latexpdf changes linkcheck doctest xml \
+	pseudoxml
 
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
 	@echo "  linkcheck  to check all external links for integrity"
 
 clean:
-	-rm -rf _build/*
+	rm -rf _build/*
 
 html:
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) _build/html
 	@echo "Running Texinfo files through makeinfo..."
 	make -C _build/texinfo info
 	@echo "makeinfo finished; the Info files are in _build/texinfo."
+
+xml:
+	$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) _build/xml
+	@echo
+	@echo "Build finished. The XML files are in _build/XML."
+
+pseudoxml:
+	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) _build/pseudoxml
+	@echo
+	@echo "Build finished. The pseudo-XML files are in _build/pseudoxml."
Add a comment to this file

doc/_static/pocoo.png

Old
Old image
New
New image

doc/_templates/index.html

     documentation of Python projects, but C/C++ is already supported as well,
     and it is planned to add special support for other languages as well.  Of
     course, this site is also created from reStructuredText sources using
-    Sphinx!
-  </p>
-  <p>
-    Sphinx is under constant development.  The following features are present,
-    work fine and can be seen &#8220;in action&#8221; in the Python docs:
+    Sphinx!  The following features should be highlighted:
   </p>
   <ul>
     <li><b>Output formats:</b> HTML (including Windows HTML Help), LaTeX (for
-      printable PDF versions), manual pages, plain text</li>
+      printable PDF versions), Texinfo, manual pages, plain text</li>
     <li><b>Extensive cross-references:</b> semantic markup and automatic links
       for functions, classes, citations, glossary terms and similar pieces of
       information</li>
     <li><b>Hierarchical structure:</b> easy definition of a document tree, with
       automatic links to siblings, parents and children</li>
-    <li><b>Automatic indices:</b> general index as well as a module index</li>
+    <li><b>Automatic indices:</b> general index as well as a language-specific
+      module indices</li>
     <li><b>Code handling:</b> automatic highlighting using the <a
       href="http://pygments.org">Pygments</a> highlighter</li>
     <li><b>Extensions:</b> automatic testing of code snippets, inclusion of
-      docstrings from Python modules (API docs), and more</li>
+      docstrings from Python modules (API docs), and
+      <a href="{{ pathto('ext') }}">more</a></li>
   </ul>
   <p>
     Sphinx uses <a href="http://docutils.sf.net/rst.html">reStructuredText</a>
     suite, the <a href="http://docutils.sf.net/">Docutils</a>.
   </p>
 
-  <h2>Documentation</h2>
+  <h2 style="margin-bottom: 0">Documentation</h2>
 
   <table class="contentstable" align="center" style="margin-left: 30px"><tr>
     <td width="50%">
 
   <p>
     You can also download PDF versions of the Sphinx documentation:
-    a <a href="http://sphinx.pocoo.org/sphinx.pdf">version</a> generated from
+    a <a href="http://sphinx-doc.org/sphinx.pdf">version</a> generated from
     the LaTeX Sphinx produces, and
-    a <a href="http://sphinx.pocoo.org/sphinx-rst2pdf.pdf">version</a> generated
+    a <a href="http://sphinx-doc.org/sphinx-rst2pdf.pdf">version</a> generated
     by rst2pdf.
   </p>
 
   <p>There is a <a href="http://sphinx-users.jp/doc10/">Japanese translation</a>
     of this documentation, thanks to Yoshiki Shibukawa.</p>
 
-  <h2>Get Sphinx</h2>
-  <p>
-    Sphinx is available as an <a
-    href="http://peak.telecommunity.com/DevCenter/EasyInstall">easy-install</a>able
-    package on the <a href="http://pypi.python.org/pypi/Sphinx">Python Package
-    Index</a>.
-  </p>
-  <p>The code can be found in a Mercurial repository, at
-    <tt>http://bitbucket.org/birkenfeld/sphinx/</tt>.</p>
-
 {% endblock %}

doc/_templates/indexsidebar.html

-<p class="logo"><a href="http://pocoo.org/">
-  <img src="{{ pathto("_static/pocoo.png", 1) }}" /></a></p>
+<p class="logo">A <a href="http://pocoo.org/">
+  <img src="{{ pathto("_static/pocoo.png", 1) }}" /></a> project</a></p>
 
 <h3>Download</h3>
 {% if version.endswith('(hg)') %}
 <p>Get Sphinx from the <a href="http://pypi.python.org/pypi/Sphinx">Python Package
 Index</a>, or install it with:</p>
 <pre>easy_install -U Sphinx</pre>
-<p>Latest <a href="http://sphinx.pocoo.org/latest/">development version docs</a>
+<p>Latest <a href="http://sphinx-doc.org/latest/">development version docs</a>
 are also available.</p>
 {% endif %}
 
 <h3>Questions? Suggestions?</h3>
 
-<p>Join the <a href="http://groups.google.com/group/sphinx-dev">Google group</a>:</p>
-<form action="http://groups.google.com/group/sphinx-dev/boxsubscribe"
-      style="padding-left: 1em">
-  <input type="text" name="email" value="your@email"/>
-  <input type="submit" name="sub" value="Subscribe" />
+<p>Join the <a href="http://groups.google.com/group/sphinx-users">Google group</a>:</p>
+<form action="http://groups.google.com/group/sphinx-users/boxsubscribe"
+      style="padding-left: 0.5em">
+  <input type="text" name="email" value="your@email" style="font-size: 90%; width: 120px"
+         onfocus="$(this).val('');"/>
+  <input type="submit" name="sub" value="Subscribe" style="font-size: 90%; width: 70px"/>
 </form>
 <p>or come to the <tt>#pocoo</tt> channel on FreeNode.</p>
 <p>You can also open an issue at the

doc/_templates/layout.html

-{% extends "!layout.html" %}
-
-{% block extrahead %}
-{{ super() }}
-{%- if not embedded %}
-<style type="text/css">
-  table.right { float: right; margin-left: 20px; }
-  table.right td { border: 1px solid #ccc; }
-</style>
-{%- endif %}
-{% endblock %}
-
-{% block rootrellink %}
-        <li><a href="{{ pathto('index') }}">Sphinx home</a>&nbsp;|&nbsp;</li>
-        <li><a href="{{ pathto('contents') }}">Documentation</a>
-          &raquo;</li>
-{% endblock %}
-
-{% block header %}
-<div style="background-color: white; text-align: left; padding: 10px 10px 15px 15px">
-<img src="{{ pathto("_static/sphinx.png", 1) }}" alt="Sphinx logo" />
-</div>
-{% endblock %}

doc/_themes/sphinx13/layout.html

+{#
+    sphinxdoc/layout.html
+    ~~~~~~~~~~~~~~~~~~~~~
+
+    Sphinx layout template for the sphinxdoc theme.
+
+    :copyright: Copyright 2007-2013 by the Sphinx team, see AUTHORS.
+    :license: BSD, see LICENSE for details.
+#}
+{%- extends "basic/layout.html" %}
+
+{# put the sidebar before the body #}
+{% block sidebar1 %}{{ sidebar() }}{% endblock %}
+{% block sidebar2 %}{% endblock %}
+
+{% block extrahead %}
+    <link href='http://fonts.googleapis.com/css?family=Open+Sans:300,400,700'
+          rel='stylesheet' type='text/css'>
+{{ super() }}
+{%- if not embedded %}
+    <style type="text/css">
+      table.right { float: right; margin-left: 20px; }
+      table.right td { border: 1px solid #ccc; }
+      {% if pagename == 'index' %}
+      .related { display: none; }
+      {% endif %}
+    </style>
+    <script type="text/javascript">
+      // intelligent scrolling of the sidebar content
+      $(window).scroll(function() {
+        var sb = $('.sphinxsidebarwrapper');
+        var win = $(window);
+        var sbh = sb.height();
+        var offset = $('.sphinxsidebar').position()['top'];
+        var wintop = win.scrollTop();
+        var winbot = wintop + win.innerHeight();
+        var curtop = sb.position()['top'];
+        var curbot = curtop + sbh;
+        // does sidebar fit in window?
+        if (sbh < win.innerHeight()) {
+          // yes: easy case -- always keep at the top
+          sb.css('top', $u.min([$u.max([0, wintop - offset - 10]),
+                                $(document).height() - sbh - 200]));
+        } else {
+          // no: only scroll if top/bottom edge of sidebar is at
+          // top/bottom edge of window
+          if (curtop > wintop && curbot > winbot) {
+            sb.css('top', $u.max([wintop - offset - 10, 0]));
+          } else if (curtop < wintop && curbot < winbot) {
+            sb.css('top', $u.min([winbot - sbh - offset - 20,
+                                  $(document).height() - sbh - 200]));
+          }
+        }
+      });
+    </script>
+{%- endif %}
+{% endblock %}
+
+{% block rootrellink %}
+        <li><a href="{{ pathto('index') }}">Sphinx home</a>&nbsp;|</li>
+        <li><a href="{{ pathto('contents') }}">Documentation</a> &raquo;</li>
+{% endblock %}
+
+{% block header %}
+<div class="pageheader">
+  <ul>
+    <li><a href="{{ pathto('index') }}">Home</a></li>
+    <li><a href="{{ pathto('install') }}">Get it</a></li>
+    <li><a href="{{ pathto('contents') }}">Docs</a></li>
+    <li><a href="{{ pathto('develop') }}">Extend/Develop</a></li>
+  </ul>
+  <div>
+    <a href="{{ pathto('index') }}">
+      <img src="{{ pathto('_static/sphinxheader.png', 1) }}" alt="SPHINX" />
+    </a>
+  </div>
+</div>
+{% endblock %}
Add a comment to this file

doc/_themes/sphinx13/static/bodybg.png

Added
New image
Add a comment to this file

doc/_themes/sphinx13/static/footerbg.png

Added
New image
Add a comment to this file

doc/_themes/sphinx13/static/headerbg.png

Added
New image
Add a comment to this file

doc/_themes/sphinx13/static/listitem.png

Added
New image
Add a comment to this file

doc/_themes/sphinx13/static/relbg.png

Added
New image

doc/_themes/sphinx13/static/sphinx13.css

+/*
+ * sphinx13.css
+ * ~~~~~~~~~~~~
+ *
+ * Sphinx stylesheet -- sphinx13 theme.
+ *
+ * :copyright: Copyright 2007-2013 by the Sphinx team, see AUTHORS.
+ * :license: BSD, see LICENSE for details.
+ *
+ */
+
+@import url("basic.css");
+
+/* -- page layout ----------------------------------------------------------- */
+
+body {
+    font-family: 'Open Sans', 'Lucida Grande', 'Lucida Sans Unicode', 'Geneva',
+                 'Verdana', sans-serif;
+    font-size: 14px;
+    text-align: center;
+    background-image: url(bodybg.png);
+    color: black;
+    padding: 0;
+    border-right: 1px solid #0a507a;
+    border-left: 1px solid #0a507a;
+
+    margin: 0 auto;
+    min-width: 780px;
+    max-width: 1080px;
+}
+
+.pageheader {
+    background-image: url(headerbg.png);
+    text-align: left;
+    padding: 10px 15px;
+}
+
+.pageheader ul {
+    float: right;
+    color: white;
+    list-style-type: none;
+    padding-left: 0;
+    margin-top: 30px;
+    margin-right: 10px;
+}
+
+.pageheader li {
+    float: left;
+    margin: 0 0 0 10px;
+}
+
+.pageheader li a {
+    border-radius: 1px;
+    padding: 8px 12px;
+    color: #f9f9f0;
+    text-shadow: 0 0 5px rgba(0, 0, 0, 0.5);
+}
+
+.pageheader li a:hover {
+    background-color: #f9f9f0;
+    color: #0a507a;
+    text-shadow: none;
+}
+
+div.document {
+    background-color: white;
+    text-align: left;
+}
+
+div.bodywrapper {
+    margin: 0 240px 0 0;
+    border-right: 1px solid #0a507a;
+}
+
+div.body {
+    margin: 0;
+    padding: 0.5em 20px 20px 20px;
+}
+
+div.related {
+    font-size: 1em;
+    color: white;
+}
+
+div.related ul {
+    background-image: url(relbg.png);
+    height: 1.9em;
+    border-top: 1px solid #002e50;
+    border-bottom: 1px solid #002e50;
+}
+
+div.related ul li {
+    margin: 0 5px 0 0;
+    padding: 0;
+    float: left;
+}
+
+div.related ul li.right {
+    float: right;
+    margin-right: 5px;
+}
+
+div.related ul li a {
+    margin: 0;
+    padding: 0 5px 0 5px;
+    line-height: 1.75em;
+    color: #f9f9f0;
+    text-shadow: 0px 0px 1px rgba(0, 0, 0, 0.5);
+}
+
+div.related ul li a:hover {
+    color: white;
+    /*text-decoration: underline;*/
+    text-shadow: 0px 0px 1px rgba(255, 255, 255, 0.5);
+}
+
+div.sphinxsidebarwrapper {
+    position: relative;
+    top: 0px;
+    padding: 0;
+}
+
+div.sphinxsidebar {
+    margin: 0;
+    padding: 0 15px 15px 0;
+    width: 210px;
+    float: right;
+    font-size: 1em;
+    text-align: left;
+}
+
+div.sphinxsidebar .logo {
+    font-size: 1.8em;
+    color: #0A507A;
+    font-weight: 300;
+    text-align: center;
+}
+
+div.sphinxsidebar .logo img {
+    vertical-align: middle;
+}
+
+div.sphinxsidebar input {
+    border: 1px solid #aaa;
+    font-family: 'Open Sans', 'Lucida Grande', 'Lucida Sans Unicode', 'Geneva',
+                 'Verdana', sans-serif;
+    font-size: 1em;
+}
+
+div.sphinxsidebar h3 {
+    font-size: 1.5em;
+    border-top: 1px solid #0a507a;
+    margin-top: 1em;
+    margin-bottom: 0.5em;
+    padding-top: 0.5em;
+}
+
+div.sphinxsidebar h4 {
+    font-size: 1.2em;
+    margin-bottom: 0;
+}
+
+div.sphinxsidebar h3, div.sphinxsidebar h4 {
+    margin-right: -15px;
+    margin-left: -15px;
+    padding-right: 14px;
+    padding-left: 14px;
+    color: #333;
+    font-weight: 300;
+    /*text-shadow: 0px 0px 0.5px rgba(0, 0, 0, 0.4);*/
+}
+
+div.sphinxsidebarwrapper > h3:first-child {
+    margin-top: 0.5em;
+    border: none;
+}
+
+div.sphinxsidebar h3 a {
+    color: #333;
+}
+
+div.sphinxsidebar ul {
+    color: #444;
+    margin-top: 7px;
+    padding: 0;
+    line-height: 130%;
+}
+
+div.sphinxsidebar ul ul {
+    margin-left: 20px;
+    list-style-image: url(listitem.png);
+}
+
+div.footer {
+    background-image: url(footerbg.png);
+    color: #ccc;
+    text-shadow: 0 0 .2px rgba(255, 255, 255, 0.8);
+    padding: 3px 8px 3px 0;
+    clear: both;
+    font-size: 0.8em;
+    text-align: right;
+}
+
+/* no need to make a visible link to Sphinx on the Sphinx page */
+div.footer a {
+    color: #ccc;
+}
+
+/* -- body styles ----------------------------------------------------------- */
+
+p {    
+    margin: 0.8em 0 0.5em 0;
+}
+
+a {
+    color: #A2881D;
+    text-decoration: none;
+}
+
+a:hover {
+    color: #E1C13F;
+}
+
+div.body a {
+    text-decoration: underline;
+}
+
+h1 {
+    margin: 10px 0 0 0;
+    font-size: 2.4em;
+    color: #0A507A;
+    font-weight: 300;
+}
+
+h2 {
+    margin: 1.em 0 0.2em 0;
+    font-size: 1.5em;
+    font-weight: 300;
+    padding: 0;
+    color: #174967;
+}
+
+h3 {
+    margin: 1em 0 -0.3em 0;
+    font-size: 1.3em;
+    font-weight: 300;
+}
+
+div.body h1 a, div.body h2 a, div.body h3 a, div.body h4 a, div.body h5 a, div.body h6 a {
+    text-decoration: none;
+}
+
+div.body h1 a tt, div.body h2 a tt, div.body h3 a tt, div.body h4 a tt, div.body h5 a tt, div.body h6 a tt {
+    color: #0A507A !important;
+    font-size: inherit !important;
+}
+
+a.headerlink {
+    color: #0A507A !important;
+    font-size: 12px;
+    margin-left: 6px;
+    padding: 0 4px 0 4px;
+    text-decoration: none !important;
+    float: right;
+}
+
+a.headerlink:hover {
+    background-color: #ccc;
+    color: white!important;
+}
+
+cite, code, tt {
+    font-family: 'Consolas', 'DejaVu Sans Mono',
+                 'Bitstream Vera Sans Mono', monospace;
+    font-size: 14px;
+    letter-spacing: -0.02em;
+}
+
+tt {
+    background-color: #f2f2f2;
+    border: 1px solid #ddd;
+    border-radius: 2px;
+    color: #333;
+    padding: 1px;
+}
+
+tt.descname, tt.descclassname, tt.xref {
+    border: 0;
+}
+
+hr {
+    border: 1px solid #abc;
+    margin: 2em;
+}
+
+a tt {
+    border: 0;
+    color: #a2881d;
+}
+
+a tt:hover {
+    color: #e1c13f;
+}
+
+pre {
+    font-family: 'Consolas', 'DejaVu Sans Mono',
+                 'Bitstream Vera Sans Mono', monospace;
+    font-size: 13px;
+    letter-spacing: 0.015em;
+    line-height: 120%;
+    padding: 0.5em;
+    border: 1px solid #ccc;
+    border-radius: 2px;
+    background-color: #f8f8f8;
+}
+
+pre a {
+    color: inherit;
+    text-decoration: underline;
+}
+
+td.linenos pre {
+    padding: 0.5em 0;
+}
+
+div.quotebar {
+    background-color: #f8f8f8;
+    max-width: 250px;
+    float: right;
+    padding: 0px 7px;
+    border: 1px solid #ccc;
+    margin-left: 1em;
+}
+
+div.topic {
+    background-color: #f8f8f8;
+}
+
+table {
+    border-collapse: collapse;
+    margin: 0 -0.5em 0 -0.5em;
+}
+
+table td, table th {
+    padding: 0.2em 0.5em 0.2em 0.5em;
+}
+
+div.admonition, div.warning {
+    font-size: 0.9em;
+    margin: 1em 0 1em 0;
+    border: 1px solid #86989B;
+    border-radius: 2px;
+    background-color: #f7f7f7;
+    padding: 0;
+}
+
+div.admonition p, div.warning p {
+    margin: 0.5em 1em 0.5em 1em;
+    padding: 0;
+}
+
+div.admonition pre, div.warning pre {
+    margin: 0.4em 1em 0.4em 1em;
+}
+
+div.admonition p.admonition-title,
+div.warning p.admonition-title {
+    margin-top: 1em;
+    padding-top: 0.5em;
+    font-weight: bold;
+}
+
+div.warning {
+    border: 1px solid #940000;
+/*    background-color: #FFCCCF;*/
+}
+
+div.warning p.admonition-title {
+}
+
+div.admonition ul, div.admonition ol,
+div.warning ul, div.warning ol {
+    margin: 0.1em 0.5em 0.5em 3em;
+    padding: 0;
+}
+
+.viewcode-back {
+    font-family: 'Open Sans', 'Lucida Grande', 'Lucida Sans Unicode', 'Geneva',
+                 'Verdana', sans-serif;
+}
+
+div.viewcode-block:target {
+    background-color: #f4debf;
+    border-top: 1px solid #ac9;
+    border-bottom: 1px solid #ac9;
+}
Add a comment to this file

doc/_themes/sphinx13/static/sphinxheader.png

Added
New image

doc/_themes/sphinx13/theme.conf

+[theme]
+inherit = basic
+stylesheet = sphinx13.css
+pygments_style = trac
 
    Its name is ``linkcheck``.
 
+.. module:: sphinx.builders.xml
+.. class:: XMLBuilder
+
+   This builder produces Docutils-native XML files.  The output can be
+   transformed with standard XML tools such as XSLT processors into arbitrary
+   final forms.
+
+   Its name is ``xml``.
+
+   .. versionadded:: 1.2
+
+.. class:: PseudoXMLBuilder
+
+   This builder is used for debugging the Sphinx/Docutils "Reader to Transform
+   to Writer" pipeline. It produces compact pretty-printed "pseudo-XML", files
+   where nesting is indicated by indentation (no end-tags). External
+   attributes for all elements are output, and internal attributes for any
+   leftover "pending" elements are also given.
+
+   Its name is ``pseudoxml``.
+
+   .. versionadded:: 1.2
+
 
 Built-in Sphinx extensions that offer more builders are:
 
 exclude_patterns = ['_build']
 
 project = 'Sphinx'
-copyright = '2007-2011, Georg Brandl'
+copyright = '2007-2013, Georg Brandl'
 version = sphinx.__released__
 release = version
 show_authors = True
 
-html_theme = 'sphinxdoc'
+html_theme = 'sphinx13'
+html_theme_path = ['_themes']
 modindex_common_prefix = ['sphinx.']
 html_static_path = ['_static']
 html_sidebars = {'index': ['indexsidebar.html', 'searchbox.html']}
 html_additional_pages = {'index': 'index.html'}
-html_use_opensearch = 'http://sphinx.pocoo.org'
+html_use_opensearch = 'http://sphinx-doc.org'
 
 htmlhelp_basename = 'Sphinxdoc'
 
 epub_theme = 'epub'
 epub_basename = 'sphinx'
 epub_author = 'Georg Brandl'
-epub_publisher = 'http://sphinx.pocoo.org/'
+epub_publisher = 'http://sphinx-doc.org/'
 epub_scheme = 'url'
 epub_identifier = epub_publisher
 epub_pre_files = [('index.html', 'Welcome')]
    * ``ko`` -- Korean
    * ``lt`` -- Lithuanian
    * ``lv`` -- Latvian
+   * ``nb_NO`` -- Norwegian Bokmal
    * ``ne`` -- Nepali
    * ``nl`` -- Dutch
    * ``pl`` -- Polish
 
    .. versionadded:: 1.1
 
+.. confval:: html_search_scorer
+
+   The name of a javascript file (relative to the configuration directory) that
+   implements a search results scorer.  If empty, the default will be used.
+
+   .. XXX describe interface for scorer here
+
+   .. versionadded:: 1.2
+
 .. confval:: htmlhelp_basename
 
    Output file base name for HTML help builder.  Default is ``'pydoc'``.
    .. versionadded:: 1.2
 
 
+Options for the XML builder
+---------------------------
+
+.. confval:: xml_pretty
+
+   If True, pretty-print the XML.  Default is ``True``.
+
+   .. versionadded:: 1.2
+
+
 .. rubric:: Footnotes
 
 .. [1] A note on available globbing syntax: you can use the standard shell
 
    faq
    glossary
+   devguide
    changes
    examples
 
+:orphan:
+
+Sphinx development
+==================
+
+Sphinx is a maintained by a group of volunteers.  We value every contribution!
+
+* The code can be found in a Mercurial repository, at
+  http://bitbucket.org/birkenfeld/sphinx/.
+* Issues and feature requests should be raised in the `tracker
+  <http://bitbucket.org/birkenfeld/sphinx/issues/>`_.
+* The mailing list for development is at `Google Groups
+  <http://groups.google.com/group/sphinx-dev/>`_.
+
+For more about our development process and methods, see the :doc:`devguide`.
+
+Extensions
+==========
+
+The `sphinx-contrib <http://bitbucket.org/birkenfeld/sphinx-contrib/>`_
+repository contains many contributed extensions.  Some of them have their own
+releases on PyPI, others you can install from a checkout.
+
+This is the current list of contributed extensions in that repository:
+
+- aafig: render embeded ASCII art as nice images using aafigure_.
+- actdiag: embed activity diagrams by using actdiag_
+- adadomain: an extension for Ada support (Sphinx 1.0 needed)
+- ansi: parse ANSI color sequences inside documents
+- autorun: Execute code in a runblock directive.
+- blockdiag: embed block diagrams by using blockdiag_
+- cheeseshop: easily link to PyPI packages
+- clearquest: create tables from ClearQuest_ queries.
+- coffeedomain: a domain for (auto)documenting CoffeeScript source code.
+- context: a builder for ConTeXt.
+- doxylink: Link to external Doxygen-generated HTML documentation
+- email: obfuscate email addresses
+- erlangdomain: an extension for Erlang support (Sphinx 1.0 needed)
+- exceltable: embed Excel spreadsheets into documents using exceltable_
+- feed: an extension for creating syndication feeds and time-based overviews
+  from your site content
+- gnuplot: produces images using gnuplot_ language.
+- googleanalytics: track html visitors statistics
+- googlechart: embed charts by using `Google Chart`_
+- googlemaps: embed maps by using `Google Maps`_
+- httpdomain: a domain for documenting RESTful HTTP APIs.
+- hyphenator: client-side hyphenation of HTML using hyphenator_
+- lilypond: an extension inserting music scripts from Lilypond_ in PNG format.
+- mscgen: embed mscgen-formatted MSC (Message Sequence Chart)s.
+- nicoviceo: embed videos from nicovideo
+- nwdiag: embed network diagrams by using nwdiag_
+- omegat: support tools to collaborate with OmegaT_ (Sphinx 1.1 needed)
+- osaka: convert standard Japanese doc to Osaka dialect (it is joke extension)
+- paverutils: an alternate integration of Sphinx with Paver_.
+- phpdomain: an extension for PHP support
+- plantuml: embed UML diagram by using PlantUML_
+- rawfiles: copy raw files, like a CNAME.
+- requirements: declare requirements wherever you need (e.g. in test
+  docstrings), mark statuses and collect them in a single list
+- rubydomain: an extension for Ruby support (Sphinx 1.0 needed)
+- sadisplay: display SqlAlchemy model sadisplay_
+- sdedit: an extension inserting sequence diagram by using Quick Sequence.
+  Diagram Editor (sdedit_)
+- seqdiag: embed sequence diagrams by using seqdiag_
+- slide: embed presentation slides on slideshare_ and other sites.
+- swf: embed flash files
+- sword: an extension inserting Bible verses from Sword_.
+- tikz: draw pictures with the `TikZ/PGF LaTeX package`_.
+- traclinks: create TracLinks_ to a Trac_ instance from within Sphinx
+- whooshindex: whoosh indexer extension
+- youtube: embed videos from YouTube_
+- zopeext: provide an ``autointerface`` directive for using `Zope interfaces`_.
+
+
+See the :ref:`extension tutorial <exttut>` on getting started with writing your
+own extensions.
+
+
+.. _aafigure: https://launchpad.net/aafigure
+.. _gnuplot: http://www.gnuplot.info/
+.. _paver: http://www.blueskyonmars.com/projects/paver/
+.. _Sword: http://www.crosswire.org/sword/
+.. _Lilypond: http://lilypond.org/web/
+.. _sdedit: http://sdedit.sourceforge.net/
+.. _Trac: http://trac.edgewall.org
+.. _TracLinks: http://trac.edgewall.org/wiki/TracLinks
+.. _OmegaT: http://www.omegat.org/
+.. _PlantUML: http://plantuml.sourceforge.net/
+.. _PyEnchant: http://www.rfk.id.au/software/pyenchant/
+.. _sadisplay: http://bitbucket.org/estin/sadisplay/wiki/Home
+.. _blockdiag: http://blockdiag.com/
+.. _seqdiag: http://blockdiag.com/
+.. _actdiag: http://blockdiag.com/
+.. _nwdiag: http://blockdiag.com/
+.. _Google Chart: http://code.google.com/intl/ja/apis/chart/
+.. _Google Maps: http://maps.google.com/
+.. _hyphenator: http://code.google.com/p/hyphenator/
+.. _exceltable: http://packages.python.org/sphinxcontrib-exceltable/
+.. _YouTube: http://www.youtube.com/
+.. _ClearQuest: http://www-01.ibm.com/software/awdtools/clearquest/
+.. _Zope interfaces: http://docs.zope.org/zope.interface/README.html
+.. _slideshare: http://www.slideshare.net/
+.. _TikZ/PGF LaTeX package: http://sourceforge.net/projects/pgf/
+Sphinx Developer's Guide
+========================
+
+.. topic:: Abstract
+
+   This document describes the development process of Sphinx, a documentation
+   system used by developers to document systems used by other developers to
+   develop other systems that may also be documented using Sphinx.
+
+The Sphinx source code is managed using `Mercurial`_ and is hosted on
+`BitBucket`_.
+
+    hg clone https://bitbucket.org/birkenfeld/sphinx
+
+.. rubric:: Community
+
+sphinx-users <sphinx-users@googlegroups.com>
+    Mailing list for user support.
+
+sphinx-dev <sphinx-dev@googlegroups.com>
+    Mailing list for development related discussions.
+
+#pocoo on irc.freenode.net
+    IRC channel for development questions and user support.
+
+    This channel is shared with other Pocoo projects.  Archived logs are
+    available `here <http://dev.pocoo.org/irclogs/>`_.
+
+.. _`BitBucket`: http://bitbucket.org
+.. _`Mercurial`: http://mercurial.selenic.com/
+
+
+Bug Reports and Feature Requests
+--------------------------------
+
+If you have encountered a problem with Sphinx or have an idea for a new
+feature, please submit it to the `issue tracker`_ on BitBucket or discuss it
+on the sphinx-dev mailing list.
+
+For bug reports, please include the output produced during the build process
+and also the log file Sphinx creates after it encounters an un-handled
+exception.  The location of this file should be shown towards the end of the
+error message.
+
+Including or providing a link to the source files involved may help us fix the
+issue.  If possible, try to create a minimal project that produces the error
+and post that instead.
+
+.. _`issue tracker`: http://bitbucket.org/birkenfeld/sphinx/issues
+
+
+Contributing to Sphinx
+----------------------
+
+The recommended way for new contributors to submit code to Sphinx is to fork
+the Mercurial repository on BitBucket and then submit a pull request after
+committing the changes.  The pull request will then need to be approved by one
+of the core developers before it is merged into the main repository.
+
+
+Getting Started
+~~~~~~~~~~~~~~~
+
+These are the basic steps needed to start developing on Sphinx.
+
+#. Create an account on BitBucket.
+
+#. Fork the main Sphinx repository (`birkenfeld/sphinx
+   <https://bitbucket.org/birkenfeld/sphinx>`_) using the BitBucket interface.
+
+#. Clone the forked repository to your machine. ::
+
+       hg clone https://bitbucket.org/USERNAME/sphinx-fork
+       cd sphinx-fork
+
+#. Checkout the appropriate branch.
+
+   For changes that should be included in the next minor release (namely bug
+   fixes), use the ``stable`` branch. ::
+
+       hg checkout stable
+
+   For new features or other substantial changes that should wait until the
+   next major release, use the ``default`` branch.
+
+#. Setup your Python environment. ::
+
+       virtualenv ~/sphinxenv
+       . ~/sphinxenv/bin/activate
+       pip install -e .
+
+#. Hack, hack, hack.
+
+   For tips on working with the code, see the `Coding Guide`_.
+
+#. Test, test, test.
+
+   Run the unit tests::
+
+       pip install nose
+       make test
+
+   Build the documentation and check the output for different builders::
+
+       cd docs
+       make clean html text man info latexpdf
+
+   Run the unit tests under different Python environments using
+   :program:`tox`::
+
+       pip install tox
+       tox -v
+
+   Add a new unit test in the ``tests`` directory if you can.
+
+   For bug fixes, first add a test that fails without your changes and passes
+   after they are applied.
+
+#. Commit your changes. ::
+
+       hg commit -m 'Add useful new feature that does this.'
+
+   BitBucket recognizes `certain phrases`__ that can be used to automatically
+   update the issue tracker.
+
+   For example::
+
+       hg commit -m 'Closes #42: Fix invalid markup in docstring of Foo.bar.'
+
+   would close issue #42.
+
+   __ https://confluence.atlassian.com/display/BITBUCKET/Automatically+Resolving+Issues+when+Users+Push+Code
+
+#. Push changes to your forked repository on BitBucket. ::
+
+       hg push
+
+#. Submit a pull request from your repository to ``birkenfeld/sphinx`` using
+   the BitBucket interface.
+
+#. Wait for a core developer to review your changes.
+
+
+Core Developers
+~~~~~~~~~~~~~~~
+
+The core developers of Sphinx have write access to the main repository.  They
+can commit changes, accept/reject pull requests, and manage items on the issue
+tracker.
+
+You do not need to be a core developer or have write access to be involved in
+the development of Sphinx.  You can submit patches or create pull requests
+from forked repositories and have a core developer add the changes for you.
+
+The following are some general guidelines for core developers:
+
+* Questionable or extensive changes should be submitted as a pull request
+  instead of being committed directly to the main repository.  The pull
+  request should be reviewed by another core developer before it is merged.
+
+* Trivial changes can be committed directly but be sure to keep the repository
+  in a good working state and that all tests pass before pushing your changes.
+
+* When committing code written by someone else, please attribute the original
+  author in the commit message and any relevant :file:`CHANGES` entry.
+
+* Using Mercurial named branches other than ``default`` and ``stable`` is not
+  encouraged.
+
+
+Coding Guide
+------------
+
+* Try to use the same code style as used in the rest of the project.  See the
+  `Pocoo Styleguide`__ for more information.
+
+  __ http://flask.pocoo.org/docs/styleguide/
+
+* For non-trivial changes, please update the :file:`CHANGES` file.  If your
+  changes alter existing behavior, please document this.
+
+* New features should be documented.  Include examples and use cases where
+  appropriate.  If possible, include a sample that is displayed in the
+  generated output.
+
+* When adding a new configuration variable, be sure to document it and update
+  :file:`sphinx/quickstart.py`.
+
+* Use the included :program:`utils/check_sources.py` script to check for
+  common formatting issues (trailing whitespace, lengthy lines, etc).
+
+* Add appropriate unit tests.
+
+
+Debugging Tips
+~~~~~~~~~~~~~~
+
+* Delete the build cache before building documents if you make changes in the
+  code by running the command ``make clean`` or using the
+  :option:`sphinx-build -E` option.
+
+* Use the :option:`sphinx-build -P` option to run Pdb on exceptions.
+
+* Use ``node.pformat()`` and ``node.asdom().toxml()`` to generate a printable
+  representation of the document structure.
+
+* Set the configuration variable :confval:`keep_warnings` to True so warnings
+  will be displayed in the generated output.
+
+* Set the configuration variable :confval:`nitpicky` to True so that Sphinx
+  will complain about references without a known target.
+
+* Set the debugging options in the `Docutils configuration file
+  <http://docutils.sourceforge.net/docs/user/config.html>`_.
 ------------
 
 The sphinx-contrib_ repository contains more domains available as extensions;
-currently Ada, Erlang, HTTP, PHP, and Ruby domains.
+currently Ada, CoffeeScript_, Erlang_, HTTP_, Jinja_, PHP_, Ruby, and Scala_
+domains.
 
 
 .. _sphinx-contrib: https://bitbucket.org/birkenfeld/sphinx-contrib/
+
+.. _CoffeeScript: http://pypi.python.org/pypi/sphinxcontrib-coffee
+.. _Erlang: http://pypi.python.org/pypi/sphinxcontrib-erlangdomain
+.. _HTTP: http://pypi.python.org/pypi/sphinxcontrib-httpdomain
+.. _Jinja: http://pypi.python.org/pypi/sphinxcontrib-jinjadomain
+.. _Scala: http://pypi.python.org/pypi/sphinxcontrib-scaladomain
+.. _PHP: http://pypi.python.org/pypi/sphinxcontrib-phpdomain

doc/ext/linkcode.rst

+:mod:`sphinx.ext.linkcode` -- Add external links to source code
+===============================================================
+
+.. module:: sphinx.ext.linkcode
+   :synopsis: Add external links to source code.
+.. moduleauthor:: Pauli Virtanen
+
+.. versionadded:: 1.2
+
+This extension looks at your object descriptions (``.. class::``,
+``.. function::`` etc.) and adds external links to code hosted
+somewhere on the web. The intent is similar to the
+``sphinx.ext.viewcode`` extension, but assumes the source code can be
+found somewhere on the Internet.
+
+In your configuration, you need to specify a :confval:`linkcode_resolve`
+function that returns an URL based on the object.
+
+.. confval:: linkcode_resolve
+
+   This is a function ``linkcode_resolve(domain, info)``,
+   which should return the URL to source code corresponding to
+   the object in given domain with given information.
+
+   The function should return ``None`` if no link is to be added.
+
+   The argument ``domain`` specifies the language domain the object is
+   in. ``info`` is a dictionary with the following keys guaranteed to
+   be present (dependent on the domain):
+
+   - ``py``: ``module`` (name of the module), ``fullname`` (name of the object)
+   - ``c``: ``names`` (list of names for the object)
+   - ``cpp``: ``names`` (list of names for the object)
+   - ``javascript``: ``object`` (name of the object), ``fullname`` (name of the item)
+
+   Example:
+
+   .. code-block:: python
+
+      def linkcode_resolve(domain, info):
+          if domain != 'py':
+              return None
+          if not info['module']:
+              return None
+          filename = info['module'].replace('.', '/')
+          return "http://somesite/sourcerepo/%s.py" % filename
 .. confval:: pngmath_dvipng_args
 
    Additional arguments to give to dvipng, as a list.  The default value is
-   ``['-gamma 1.5', '-D 110']`` which makes the image a bit darker and larger
-   then it is by default.
+   ``['-gamma', '1.5', '-D', '110', '-bg', 'Transparent']`` which makes the
+   image a bit darker and larger then it is by default, and produces PNGs with a
+   transparent background.
 
-   An arguments you might want to add here is e.g. ``'-bg Transparent'``,
-   which produces PNGs with a transparent background.  This is not enabled by
-   default because some Internet Explorer versions don't like transparent PNGs.
-
-   .. note::
-
-      When you "add" an argument, you need to reproduce the default arguments if
-      you want to keep them; that is, like this::
-
-         pngmath_dvipng_args = ['-gamma 1.5', '-D 110', '-bg Transparent']
+   .. versionchanged:: 1.2
+      Now includes ``-bg Transparent`` by default.
 
 .. confval:: pngmath_use_preview
 

doc/extensions.rst