Commits

Anonymous committed a0b4b9c Merge

Merge with birkenfeld/sphinx.

Comments (0)

Files changed (348)

 ^env/
 \.DS_Store$
 ~$
+^utils/.*3\.py$
+^distribute-
+^tests/root/_build/*
+^tests/root/generated/*
 80dc1a872e49556dce681fdb2ea4be54ad847e6c 1.0b1
 b494009dccf19d0df894a4ce50754e866a099808 1.0b2
 dc883adf6424f1265e6b6d3c95c23e7c562e1206 1.0
+8c458e9894f29458a0507e747e0c3bab396a9b8a 1.0.1
+3fcdbfa3afb181d3bec533be76ab1fcb446416bb 1.0.2
+fdf329d6066499c7d4190001b0510ad5b836c810 1.0.3
+d2c100cde633828d8656a5cdefbdbc167e2768a1 1.0.4
+878a1874a8e63f1b5a6b939ed86b6c120bf168c6 1.0.5
+48688502e78b09c03b877910b64368c5db9bb4ff 1.0.6
+f7f069b6d1e5cc2d4394420be9a4a3efc0cb4d47 1.0.7
 * Andi Albrecht -- agogo theme
 * Henrique Bastos -- SVG support for graphviz extension
 * Daniel Bültmann -- todo extension
+* Etienne Desautels -- apidoc module
 * Michael Droettboom -- inheritance_diagram extension
 * Charles Duffy -- original graphviz extension
+* Kevin Dunn -- MathJax extension
 * Josip Dzolonga -- coverage builder
 * Horst Gutmann -- internationalization support
 * Martin Hans -- autodoc improvements
+* Doug Hellmann -- graphviz improvements
 * Dave Kuhlman -- original LaTeX writer
+* Blaise Laflamme -- pyramid theme
 * Thomas Lamb -- linkcheck builder
+* Łukasz Langa -- partial support for autodoc
+* Robert Lehmann -- gettext builder (GSOC project)
 * Dan MacKinlay -- metadata fixes
 * Martin Mahner -- nature theme
 * Will Maier -- directory HTML builder
+* Jacob Mason -- websupport library (GSOC project)
 * Roland Meister -- epub builder
 * Ezio Melotti -- collapsible sidebar JavaScript
-* Daniel Neuhäuser -- JavaScript domain
+* Daniel Neuhäuser -- JavaScript domain, Python 3 support (GSOC)
 * Christopher Perkins -- autosummary integration
 * Benjamin Peterson -- unittests
 * T. Powers -- HTML output improvements
 * Stefan Seefeld -- toctree improvements
+* Shibukawa Yoshiki -- pluggable search API and Japanese search
 * Antonio Valentino -- qthelp builder
 * Pauli Virtanen -- autodoc improvements, autosummary extension
 * Stefan van der Walt -- autosummary extension
+* Thomas Waldmann -- apidoc module fixes
+* John Waltman -- Texinfo builder
 * Barry Warsaw -- setup command improvements
 * Sebastian Wiesner -- image handling, distutils support
 
 Release 1.1 (in development)
 ============================
 
+Incompatible changes
+--------------------
 
-Release 1.0.1 (in development)
+* The :rst:dir:`py:module` directive doesn't output its ``platform`` option
+  value anymore.  (It was the only thing that the directive did output, and
+  therefore quite inconsistent.)
+
+Features added
+--------------
+
+* Added Python 3.x support.
+
+* New builders and subsystems:
+
+  - Added a Texinfo builder.
+  - Added i18n support for content, a ``gettext`` builder and related
+    utilities.
+  - Added the ``websupport`` library and builder.
+  - #98: Added a ``sphinx-apidoc`` script that autogenerates a hierarchy
+    of source files containing autodoc directives to document modules
+    and packages.
+  - #273: Add an API for adding full-text search support for languages
+    other than English.  Add support for Japanese.
+
+* Markup:
+
+  - #138: Add an :rst:role:`index` role, to make inline index entries.
+  - #454: Add more index markup capabilities: marking see/seealso entries,
+    and main entries for a given key.
+  - #460: Allow limiting the depth of section numbers for HTML using the
+    :rst:dir:`toctree`\'s ``numbered`` option.
+  - #586: Implemented improved :rst:dir:`glossary` markup which allows
+    multiple terms per definition.
+  - #478: Added :rst:dir:`py:decorator` directive to describe decorators.
+  - C++ domain now supports array definitions.
+  - Section headings in :rst:dir:`only` directives are now correctly
+    handled.
+
+* HTML builder:
+
+  - Added ``pyramid`` theme.
+  - #559: :confval:`html_add_permalinks` is now a string giving the
+    text to display in permalinks.
+  - #259: HTML table rows now have even/odd CSS classes to enable
+    "Zebra styling".
+  - #554: Add theme option ``sidebarwidth`` to the basic theme.
+
+* Other builders:
+
+  - #516: Added new value of the :confval:`latex_show_urls` option to
+    show the URLs in footnotes.
+  - #209: Added :confval:`text_newlines` and :confval:`text_sectionchars`
+    config values.
+  - Added :confval:`man_show_urls` config value.
+  - #472: linkcheck builder: Check links in parallel, use HTTP HEAD
+    requests and allow configuring the timeout.  New config values:
+    :confval:`linkcheck_timeout` and :confval:`linkcheck_workers`.
+  - #521: Added :confval:`linkcheck_ignore` config value.
+
+* Configuration and extensibility:
+
+  - #537: Added :confval:`nitpick_ignore`.
+  - #306: Added :event:`env-get-outdated` event.
+
+* Autodoc:
+
+  - #564: Add :confval:`autodoc_docstring_signature`.  When enabled (the
+    default), autodoc retrieves the signature from the first line of the
+    docstring, if it is found there.
+  - #176: Provide ``private-members`` option for autodoc directives.
+  - #520: Provide ``special-members`` option for autodoc directives.
+  - #431: Doc comments for attributes can now be given on the same line
+    as the assignment.
+  - #437: autodoc now shows values of class data attributes.
+  - autodoc now supports documenting the signatures of
+    ``functools.partial`` objects.
+
+* Other extensions:
+
+  - Added the :mod:`sphinx.ext.mathjax` extension.
+  - #443: Allow referencing external graphviz files.
+  - Added ``inline`` option to graphviz directives, and fixed the
+    default (block-style) in LaTeX output.
+  - #590: Added ``caption`` option to graphviz directives.
+  - #553: Added :rst:dir:`testcleanup` blocks in the doctest extension.
+  - #594: :confval:`trim_doctest_flags` now also removes ``<BLANKLINE>``
+    indicators.
+  - #367: Added automatic exclusion of hidden members in inheritance
+    diagrams, and an option to selectively enable it.
+  - Added :confval:`pngmath_add_tooltips`.
+
+* New locales:
+
+  - #221: Added Swedish locale.
+  - #526: Added Iranian locale.
+
+
+Release 1.0.8 (in development)
 ==============================
 
+
+Release 1.0.7 (Jan 15, 2011)
+============================
+
+* #347: Fix wrong generation of directives of static methods in
+  autosummary.
+
+* #599: Import PIL as ``from PIL import Image``.
+
+* #558: Fix longtables with captions in LaTeX output.
+
+* Make token references work as hyperlinks again in LaTeX output.
+
+* #572: Show warnings by default when reference labels cannot be
+  found.
+
+* #536: Include line number when complaining about missing reference
+  targets in nitpicky mode.
+
+* #590: Fix inline display of graphviz diagrams in LaTeX output.
+
+* #589: Build using app.build() in setup command.
+
+* Fix a bug in the inheritance diagram exception that caused base
+  classes to be skipped if one of them is a builtin.
+
+* Fix general index links for C++ domain objects.
+
+* #332: Make admonition boundaries in LaTeX output visible.
+
+* #573: Fix KeyErrors occurring on rebuild after removing a file.
+
+* Fix a traceback when removing files with globbed toctrees.
+
+* If an autodoc object cannot be imported, always re-read the
+  document containing the directive on next build.
+
+* If an autodoc object cannot be imported, show the full traceback
+  of the import error.
+
+* Fix a bug where the removal of download files and images wasn't
+  noticed.
+
+* #571: Implement ``~`` cross-reference prefix for the C domain.
+
+* Fix regression of LaTeX output with the fix of #556.
+
+* #568: Fix lookup of class attribute documentation on descriptors
+  so that comment documentation now works.
+
+* Fix traceback with ``only`` directives preceded by targets.
+
+* Fix tracebacks occurring for duplicate C++ domain objects.
+
+* Fix JavaScript domain links to objects with ``$`` in their name.
+
+
+Release 1.0.6 (Jan 04, 2011)
+============================
+
+* #581: Fix traceback in Python domain for empty cross-reference
+  targets.
+
+* #283: Fix literal block display issues on Chrome browsers.
+
+* #383, #148: Support sorting a limited range of accented characters
+  in the general index and the glossary.
+
+* #570: Try decoding ``-D`` and ``-A`` command-line arguments with
+  the locale's preferred encoding.
+
+* #528: Observe :confval:`locale_dirs` when looking for the JS
+  translations file.
+
+* #574: Add special code for better support of Japanese documents
+  in the LaTeX builder.
+
+* Regression of #77: If there is only one parameter given with
+  ``:param:`` markup, the bullet list is now suppressed again.
+
+* #556: Fix missing paragraph breaks in LaTeX output in certain
+  situations.
+
+* #567: Emit the ``autodoc-process-docstring`` event even for objects
+  without a docstring so that it can add content.
+
+* #565: In the LaTeX builder, not only literal blocks require different
+  table handling, but also quite a few other list-like block elements.
+
+* #515: Fix tracebacks in the viewcode extension for Python objects
+  that do not have a valid signature.
+
+* Fix strange reportings of line numbers for warnings generated from
+  autodoc-included docstrings, due to different behavior depending
+  on docutils version.
+
+* Several fixes to the C++ domain.
+
+
+Release 1.0.5 (Nov 12, 2010)
+============================
+
+* #557: Add CSS styles required by docutils 0.7 for aligned images
+  and figures.
+
+* In the Makefile generated by LaTeX output, do not delete pdf files
+  on clean; they might be required images.
+
+* #535: Fix LaTeX output generated for line blocks.
+
+* #544: Allow ``.pyw`` as a source file extension.
+
+
+Release 1.0.4 (Sep 17, 2010)
+============================
+
+* #524: Open intersphinx inventories in binary mode on Windows,
+  since version 2 contains zlib-compressed data.
+
+* #513: Allow giving non-local URIs for JavaScript files, e.g.
+  in the JSMath extension.
+
+* #512: Fix traceback when ``intersphinx_mapping`` is empty.
+
+
+Release 1.0.3 (Aug 23, 2010)
+============================
+
+* #495: Fix internal vs. external link distinction for links coming
+  from a docutils table-of-contents.
+
+* #494: Fix the ``maxdepth`` option for the ``toctree()`` template
+  callable when used with ``collapse=True``.
+
+* #507: Fix crash parsing Python argument lists containing brackets
+  in string literals.
+
+* #501: Fix regression when building LaTeX docs with figures that
+  don't have captions.
+
+* #510: Fix inheritance diagrams for classes that are not picklable.
+
+* #497: Introduce separate background color for the sidebar collapse
+  button, making it easier to see.
+
+* #502, #503, #496: Fix small layout bugs in several builtin themes.
+
+
+Release 1.0.2 (Aug 14, 2010)
+============================
+
+* #490: Fix cross-references to objects of types added by the
+  :func:`~.Sphinx.add_object_type` API function.
+
+* Fix handling of doc field types for different directive types.
+
+* Allow breaking long signatures, continuing with backlash-escaped
+  newlines.
+
+* Fix unwanted styling of C domain references (because of a namespace
+  clash with Pygments styles).
+
+* Allow references to PEPs and RFCs with explicit anchors.
+
+* #471: Fix LaTeX references to figures.
+
+* #482: When doing a non-exact search, match only the given type
+  of object.
+
+* #481: Apply non-exact search for Python reference targets with
+  ``.name`` for modules too.
+
+* #484: Fix crash when duplicating a parameter in an info field list.
+
+* #487: Fix setting the default role to one provided by the
+  ``oldcmarkup`` extension.
+
+* #488: Fix crash when json-py is installed, which provides a
+  ``json`` module but is incompatible to simplejson.
+
+* #480: Fix handling of target naming in intersphinx.
+
+* #486: Fix removal of ``!`` for all cross-reference roles.
+
+
+Release 1.0.1 (Jul 27, 2010)
+============================
+
+* #470: Fix generated target names for reST domain objects; they
+  are not in the same namespace.
+
+* #266: Add Bengali language.
+
+* #473: Fix a bug in parsing JavaScript object names.
+
+* #474: Fix building with SingleHTMLBuilder when there is no toctree.
+
+* Fix display names for objects linked to by intersphinx with
+  explicit targets.
+
 * Fix building with the JSON builder.
 
 * Fix hyperrefs in object descriptions for LaTeX.
   - Added Danish translation, thanks to Hjorth Larsen.
   - Added Lithuanian translation, thanks to Dalius Dobravolskas.
 
+* Bugs fixed:
 
-Release 0.6.8 (in development)
-==============================
-
-* #445: Fix links to result pages when using the search function
-  of HTML built with the ``dirhtml`` builder.
-
-* #444: In templates, properly re-escape values treated with the
-  "striptags" Jinja filter.
+  - #445: Fix links to result pages when using the search function
+    of HTML built with the ``dirhtml`` builder.
+  - #444: In templates, properly re-escape values treated with the
+    "striptags" Jinja filter.
 
 
 Release 0.6.7 (Jun 05, 2010)
 Documentation using the default theme
 -------------------------------------
 
-* APSW: http://apsw.googlecode.com/svn/publish/index.html
+* APSW: http://apidoc.apsw.googlecode.com/hg/index.html
 * ASE: https://wiki.fysik.dtu.dk/ase/
 * boostmpi: http://documen.tician.de/boostmpi/
-* Calibre: http://calibre.kovidgoyal.net/user_manual/
+* Calibre: http://calibre-ebook.com/user_manual/
 * CodePy: http://documen.tician.de/codepy/
 * Cython: http://docs.cython.org/
 * C\\C++ Python language binding project: http://language-binding.net/index.html
 * Director: http://packages.python.org/director/
-* F2py: http://www.f2py.org/html/
+* Dirigible: http://www.projectdirigible.com/documentation/
+* F2py: http://f2py.sourceforge.net/docs/
 * GeoDjango: http://geodjango.org/docs/
 * gevent: http://www.gevent.org/
 * Google Wave API: http://wave-robot-python-client.googlecode.com/svn/trunk/pydocs/index.html
 * GSL Shell: http://www.nongnu.org/gsl-shell/
+* Heapkeeper: http://heapkeeper.org/
+* Hands-on Python Tutorial: http://anh.cs.luc.edu/python/hands-on/3.1/handsonHtml/
 * Hedge: http://documen.tician.de/hedge/
 * Kaa: http://doc.freevo.org/api/kaa/
+* Leo: http://webpages.charter.net/edreamleo/front.html
+* Lino: http://lino.saffre-rumma.net/
 * MeshPy: http://documen.tician.de/meshpy/
 * mpmath: http://mpmath.googlecode.com/svn/trunk/doc/build/index.html
 * OpenEXR: http://excamera.com/articles/26/doc/index.html
 * OpenGDA: http://www.opengda.org/gdadoc/html/
 * openWNS: http://docs.openwns.org/
 * Paste: http://pythonpaste.org/script/
-* Paver: http://www.blueskyonmars.com/projects/paver/
-* Pyccuracy: http://www.pyccuracy.org/
+* Paver: http://paver.github.com/paver/
+* Pyccuracy: https://github.com/heynemann/pyccuracy/wiki/
 * PyCuda: http://documen.tician.de/pycuda/
 * Pyevolve: http://pyevolve.sourceforge.net/
 * Pylo: http://documen.tician.de/pylo/
 * IFM: http://fluffybunny.memebot.com/ifm-docs/index.html
 * LEPL: http://www.acooke.org/lepl/
 * Mayavi: http://code.enthought.com/projects/mayavi/docs/development/html/mayavi
-* NOC: http://trac.nocproject.org/trac/wiki/NocGuide
+* NOC: http://redmine.nocproject.org/projects/noc
 * NumPy: http://docs.scipy.org/doc/numpy/reference/
 * Peach^3: http://peach3.nl/doc/latest/userdoc/
-* Py on Windows: http://timgolden.me.uk/python-on-windows/
 * PyLit: http://pylit.berlios.de/
 * Sage: http://sagemath.org/doc/
 * SciPy: http://docs.scipy.org/doc/scipy/reference/
 * simuPOP: http://simupop.sourceforge.net/manual_release/build/userGuide.html
 * Sprox: http://sprox.org/
 * TurboGears: http://turbogears.org/2.0/docs/
+* Zentyal: http://doc.zentyal.org/
 * Zope: http://docs.zope.org/zope2/index.html
 * zc.async: http://packages.python.org/zc.async/1.5.0/
 
 Documentation using the sphinxdoc theme
 ---------------------------------------
 
-* Fityk: http://www.unipress.waw.pl/fityk/
+* Fityk: http://fityk.nieto.pl/
 * MapServer: http://mapserver.org/
 * Matplotlib: http://matplotlib.sourceforge.net/
 * Music21: http://mit.edu/music21/doc/html/contents.html
 * MyHDL: http://www.myhdl.org/doc/0.6/
 * NetworkX: http://networkx.lanl.gov/
 * Pweave: http://mpastell.com/pweave/
+* Pyre: http://docs.danse.us/pyre/sphinx/
 * Pysparse: http://pysparse.sourceforge.net/
 * PyTango:
   http://www.tango-controls.org/static/PyTango/latest/doc/html/index.html
-* Reteisi: http://docs.argolinux.org/reteisi/
-* Satchmo: http://www.satchmoproject.com/docs/svn/
+* Reteisi: http://www.reteisi.org/contents.html
+* Satchmo: http://www.satchmoproject.com/docs/dev/
 * Sphinx: http://sphinx.pocoo.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/
 * WebFaction: http://docs.webfaction.com/
 
 Documentation using another builtin theme
 -----------------------------------------
 
-* C/C++ Development with Eclipse: http://book.dehlia.in/c-cpp-eclipse/ (agogo)
+* C/C++ Development with Eclipse: http://eclipsebook.in/ (agogo)
 * Distribute: http://packages.python.org/distribute/ (nature)
-* Jinja: http://jinja.pocoo.org/2/documentation/ (scrolls)
+* Jinja: http://jinja.pocoo.org/ (scrolls)
 * pip: http://pip.openplans.org/ (nature)
 * Programmieren mit PyGTK und Glade (German):
   http://www.florian-diesch.de/doc/python-und-glade/online/ (agogo)
+* pypol: http://pypol.altervista.org/ (nature)
 * Spring Python: http://springpython.webfactional.com/current/sphinx/index.html
   (nature)
 * sqlparse: http://python-sqlparse.googlecode.com/svn/docs/api/index.html
 * Open ERP: http://doc.openerp.com/
 * OpenLayers: http://docs.openlayers.org/
 * PyEphem: http://rhodesmill.org/pyephem/
+* German Plone 4.0 user manual: http://www.hasecke.com/plone-benutzerhandbuch/4.0/
 * Pylons: http://pylonshq.com/docs/en/0.9.7/
 * PyMOTW: http://www.doughellmann.com/PyMOTW/
 * qooxdoo: http://manual.qooxdoo.org/current
 * Roundup: http://www.roundup-tracker.org/
 * Selenium: http://seleniumhq.org/docs/
 * Self: http://selflanguage.org/
+* Tablib: http://tablib.org/
 * SQLAlchemy: http://www.sqlalchemy.org/docs/
 * tinyTiM: http://tinytim.sourceforge.net/docs/2.0/
 * tipfy: http://www.tipfy.org/docs/
-* Werkzeug: http://werkzeug.pocoo.org/documentation/dev/
+* Werkzeug: http://werkzeug.pocoo.org/docs/
 * WFront: http://discorporate.us/projects/WFront/
 
 
 
 * Applied Mathematics at the Stellenbosch University: http://dip.sun.ac.za/
 * A personal page: http://www.dehlia.in/
-* Benoit Boissinot: http://perso.ens-lyon.fr/benoit.boissinot/
+* Benoit Boissinot: http://bboissin.appspot.com/
 * lunarsite: http://lunaryorn.de/
 * The Wine Cellar Book: http://www.thewinecellarbook.com/doc/en/
 * VOR: http://www.vor-cycling.be/
+
+
+Books produced using Sphinx
+---------------------------
+
+* "The ``repoze.bfg`` Web Application Framework":
+  http://www.amazon.com/repoze-bfg-Web-Application-Framework-Version/dp/0615345379
+* A Theoretical Physics Reference book: http://theoretical-physics.net/
+* "Simple and Steady Way of Learning for Software Engineering" (in Japanese):
+  http://www.amazon.co.jp/dp/477414259X/
+* "Expert Python Programming" (Japanese translation):
+  http://www.amazon.co.jp/dp/4048686291/
+* "Pomodoro Technique Illustrated" (Japanese translation):
+  http://www.amazon.co.jp/dp/4048689525/
+
 License for Sphinx
 ==================
 
-Copyright (c) 2007-2010 by the Sphinx team (see AUTHORS file).
+Copyright (c) 2007-2011 by the Sphinx team (see AUTHORS file).
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without
 
 include babel.cfg
 include Makefile
-include ez_setup.py
+include distribute_setup.py
 include sphinx-autogen.py
 include sphinx-build.py
 include sphinx-quickstart.py
 PYTHON ?= python
 
-export PYTHONPATH = $(shell echo "$$PYTHONPATH"):./sphinx
+.PHONY: all check clean clean-pyc clean-patchfiles clean-backupfiles \
+        clean-generated pylint reindent test covertest build convert-utils
 
-.PHONY: all check clean clean-pyc clean-patchfiles pylint reindent test
+DONT_CHECK = -i build -i dist -i sphinx/style/jquery.js \
+             -i sphinx/pycode/pgen2 -i sphinx/util/smartypants.py \
+             -i .ropeproject -i doc/_build -i tests/path.py \
+             -i tests/coverage.py -i env -i utils/convert.py \
+	     -i sphinx/search/ja.py \
+             -i utils/reindent3.py -i utils/check_sources3.py -i .tox
 
-all: clean-pyc check test
+all: clean-pyc clean-backupfiles check test
 
+ifeq ($(PYTHON), python3)
+check: convert-utils
+	@$(PYTHON) utils/check_sources3.py $(DONT_CHECK) .
+else
 check:
-	@$(PYTHON) utils/check_sources.py -i build -i dist -i sphinx/style/jquery.js \
-		-i sphinx/pycode/pgen2 -i sphinx/util/smartypants.py -i .ropeproject \
-		-i doc/_build -i ez_setup.py -i tests/path.py -i tests/coverage.py \
-		-i env -i .tox .
+	@$(PYTHON) utils/check_sources.py $(DONT_CHECK) .
+endif
 
-clean: clean-pyc clean-patchfiles
+clean: clean-pyc clean-patchfiles clean-backupfiles clean-generated
 
 clean-pyc:
 	find . -name '*.pyc' -exec rm -f {} +
 	find . -name '*.pyo' -exec rm -f {} +
-	find . -name '*~' -exec rm -f {} +
 
 clean-patchfiles:
 	find . -name '*.orig' -exec rm -f {} +
 	find . -name '*.rej' -exec rm -f {} +
 
+clean-backupfiles:
+	find . -name '*~' -exec rm -f {} +
+	find . -name '*.bak' -exec rm -f {} +
+
+clean-generated:
+	rm -f utils/*3.py*
+
 pylint:
 	@pylint --rcfile utils/pylintrc sphinx
 
+ifeq ($(PYTHON), python3)
+reindent: convert-utils
+	@$(PYTHON) utils/reindent3.py -r -n .
+else
 reindent:
-	@$(PYTHON) utils/reindent.py -r -B .
+	@$(PYTHON) utils/reindent.py -r -n .
+endif
 
-test:
+test: build
 	@cd tests; $(PYTHON) run.py -d -m '^[tT]est' $(TEST)
 
-covertest:
-	@cd tests; $(PYTHON) run.py -d -m '^[tT]est' --with-coverage --cover-package=sphinx $(TEST)
+covertest: build
+	@cd tests; $(PYTHON) run.py -d -m '^[tT]est' --with-coverage \
+		--cover-package=sphinx $(TEST)
+
+build:
+	@$(PYTHON) setup.py build
+
+ifeq ($(PYTHON), python3)
+convert-utils:
+	@python3 utils/convert.py -i utils/convert.py utils/
+endif
 Or read them online at <http://sphinx.pocoo.org/>.
 
 
+Testing
+=======
+
+To run the tests with the interpreter available as ``python``, use::
+
+    make test
+
+If you want to use a different interpreter, e.g. ``python3``, use::
+
+    PYTHON=python3 make test
+
+
 Contributing
 ============
 
Add a comment to this file

custom_fixers/__init__.py

Empty file added.

custom_fixers/fix_alt_unicode.py

+from lib2to3.fixer_base import BaseFix
+from lib2to3.fixer_util import Name
+
+class FixAltUnicode(BaseFix):
+    PATTERN = """
+    func=funcdef< 'def' name='__unicode__'
+                  parameters< '(' NAME ')' > any+ >
+    """
+
+    def transform(self, node, results):
+        name = results['name']
+        name.replace(Name('__str__', prefix=name.prefix))

distribute_setup.py

+#!python
+"""Bootstrap distribute installation
+
+If you want to use setuptools in your package's setup.py, just include this
+file in the same directory with it, and add this to the top of your setup.py::
+
+    from distribute_setup import use_setuptools
+    use_setuptools()
+
+If you want to require a specific version of setuptools, set a download
+mirror, or use an alternate download directory, you can do so by supplying
+the appropriate options to ``use_setuptools()``.
+
+This file can also be run as a script to install or upgrade setuptools.
+"""
+import os
+import sys
+import time
+import fnmatch
+import tempfile
+import tarfile
+from distutils import log
+
+try:
+    from site import USER_SITE
+except ImportError:
+    USER_SITE = None
+
+try:
+    import subprocess
+
+    def _python_cmd(*args):
+        args = (sys.executable,) + args
+        return subprocess.call(args) == 0
+
+except ImportError:
+    # will be used for python 2.3
+    def _python_cmd(*args):
+        args = (sys.executable,) + args
+        # quoting arguments if windows
+        if sys.platform == 'win32':
+            def quote(arg):
+                if ' ' in arg:
+                    return '"%s"' % arg
+                return arg
+            args = [quote(arg) for arg in args]
+        return os.spawnl(os.P_WAIT, sys.executable, *args) == 0
+
+DEFAULT_VERSION = "0.6.13"
+DEFAULT_URL = "http://pypi.python.org/packages/source/d/distribute/"
+SETUPTOOLS_FAKED_VERSION = "0.6c11"
+
+SETUPTOOLS_PKG_INFO = """\
+Metadata-Version: 1.0
+Name: setuptools
+Version: %s
+Summary: xxxx
+Home-page: xxx
+Author: xxx
+Author-email: xxx
+License: xxx
+Description: xxx
+""" % SETUPTOOLS_FAKED_VERSION
+
+
+def _install(tarball):
+    # extracting the tarball
+    tmpdir = tempfile.mkdtemp()
+    log.warn('Extracting in %s', tmpdir)
+    old_wd = os.getcwd()
+    try:
+        os.chdir(tmpdir)
+        tar = tarfile.open(tarball)
+        _extractall(tar)
+        tar.close()
+
+        # going in the directory
+        subdir = os.path.join(tmpdir, os.listdir(tmpdir)[0])
+        os.chdir(subdir)
+        log.warn('Now working in %s', subdir)
+
+        # installing
+        log.warn('Installing Distribute')
+        if not _python_cmd('setup.py', 'install'):
+            log.warn('Something went wrong during the installation.')
+            log.warn('See the error message above.')
+    finally:
+        os.chdir(old_wd)
+
+
+def _build_egg(egg, tarball, to_dir):
+    # extracting the tarball
+    tmpdir = tempfile.mkdtemp()
+    log.warn('Extracting in %s', tmpdir)
+    old_wd = os.getcwd()
+    try:
+        os.chdir(tmpdir)
+        tar = tarfile.open(tarball)
+        _extractall(tar)
+        tar.close()
+
+        # going in the directory
+        subdir = os.path.join(tmpdir, os.listdir(tmpdir)[0])
+        os.chdir(subdir)
+        log.warn('Now working in %s', subdir)
+
+        # building an egg
+        log.warn('Building a Distribute egg in %s', to_dir)
+        _python_cmd('setup.py', '-q', 'bdist_egg', '--dist-dir', to_dir)
+
+    finally:
+        os.chdir(old_wd)
+    # returning the result
+    log.warn(egg)
+    if not os.path.exists(egg):
+        raise IOError('Could not build the egg.')
+
+
+def _do_download(version, download_base, to_dir, download_delay):
+    egg = os.path.join(to_dir, 'distribute-%s-py%d.%d.egg'
+                       % (version, sys.version_info[0], sys.version_info[1]))
+    if not os.path.exists(egg):
+        tarball = download_setuptools(version, download_base,
+                                      to_dir, download_delay)
+        _build_egg(egg, tarball, to_dir)
+    sys.path.insert(0, egg)
+    import setuptools
+    setuptools.bootstrap_install_from = egg
+
+
+def use_setuptools(version=DEFAULT_VERSION, download_base=DEFAULT_URL,
+                   to_dir=os.curdir, download_delay=15, no_fake=True):
+    # making sure we use the absolute path
+    to_dir = os.path.abspath(to_dir)
+    was_imported = 'pkg_resources' in sys.modules or \
+        'setuptools' in sys.modules
+    try:
+        try:
+            import pkg_resources
+            if not hasattr(pkg_resources, '_distribute'):
+                if not no_fake:
+                    _fake_setuptools()
+                raise ImportError
+        except ImportError:
+            return _do_download(version, download_base, to_dir, download_delay)
+        try:
+            pkg_resources.require("distribute>="+version)
+            return
+        except pkg_resources.VersionConflict:
+            e = sys.exc_info()[1]
+            if was_imported:
+                sys.stderr.write(
+                "The required version of distribute (>=%s) is not available,\n"
+                "and can't be installed while this script is running. Please\n"
+                "install a more recent version first, using\n"
+                "'easy_install -U distribute'."
+                "\n\n(Currently using %r)\n" % (version, e.args[0]))
+                sys.exit(2)
+            else:
+                del pkg_resources, sys.modules['pkg_resources']    # reload ok
+                return _do_download(version, download_base, to_dir,
+                                    download_delay)
+        except pkg_resources.DistributionNotFound:
+            return _do_download(version, download_base, to_dir,
+                                download_delay)
+    finally:
+        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
+
+    `version` should be a valid distribute version number that is available
+    as an egg for download under the `download_base` URL (which should end
+    with a '/'). `to_dir` is the directory where the egg will be downloaded.
+    `delay` is the number of seconds to pause before an actual download
+    attempt.
+    """
+    # making sure we use the absolute path
+    to_dir = os.path.abspath(to_dir)
+    try:
+        from urllib.request import urlopen
+    except ImportError:
+        from urllib2 import urlopen
+    tgz_name = "distribute-%s.tar.gz" % version
+    url = download_base + tgz_name
+    saveto = os.path.join(to_dir, tgz_name)
+    src = dst = None
+    if not os.path.exists(saveto):  # Avoid repeated downloads
+        try:
+            log.warn("Downloading %s", url)
+            src = urlopen(url)
+            # Read/write all in one block, so we don't create a corrupt file
+            # if the download is interrupted.
+            data = src.read()
+            dst = open(saveto, "wb")
+            dst.write(data)
+        finally:
+            if src:
+                src.close()
+            if dst:
+                dst.close()
+    return os.path.realpath(saveto)
+
+def _no_sandbox(function):
+    def __no_sandbox(*args, **kw):
+        try:
+            from setuptools.sandbox import DirectorySandbox
+            if not hasattr(DirectorySandbox, '_old'):
+                def violation(*args):
+                    pass
+                DirectorySandbox._old = DirectorySandbox._violation
+                DirectorySandbox._violation = violation
+                patched = True
+            else:
+                patched = False
+        except ImportError:
+            patched = False
+
+        try:
+            return function(*args, **kw)
+        finally:
+            if patched:
+                DirectorySandbox._violation = DirectorySandbox._old
+                del DirectorySandbox._old
+
+    return __no_sandbox
+
+def _patch_file(path, content):
+    """Will backup the file then patch it"""
+    existing_content = open(path).read()
+    if existing_content == content:
+        # already patched
+        log.warn('Already patched.')
+        return False
+    log.warn('Patching...')
+    _rename_path(path)
+    f = open(path, 'w')
+    try:
+        f.write(content)
+    finally:
+        f.close()
+    return True
+
+_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)
+    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)
+        return False
+    found = False
+    for file in os.listdir(placeholder):
+        if fnmatch.fnmatch(file, 'setuptools*.egg-info'):
+            found = True
+            break
+    if not found:
+        log.warn('Could not locate setuptools*.egg-info')
+        return
+
+    log.warn('Removing elements out of the way...')
+    pkg_info = os.path.join(placeholder, file)
+    if os.path.isdir(pkg_info):
+        patched = _patch_egg_dir(pkg_info)
+    else:
+        patched = _patch_file(pkg_info, SETUPTOOLS_PKG_INFO)
+
+    if not patched:
+        log.warn('%s already patched.', pkg_info)
+        return False
+    # now let's move the files out of the way
+    for element in ('setuptools', 'pkg_resources.py', 'site.py'):
+        element = os.path.join(placeholder, element)
+        if os.path.exists(element):
+            _rename_path(element)
+        else:
+            log.warn('Could not find the %s element of the '
+                     'Setuptools distribution', element)
+    return True
+
+_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
+    pyver = '%s.%s' % (sys.version_info[0], sys.version_info[1])
+    setuptools_file = 'setuptools-%s-py%s.egg-info' % \
+            (SETUPTOOLS_FAKED_VERSION, pyver)
+    pkg_info = os.path.join(placeholder, setuptools_file)
+    if os.path.exists(pkg_info):
+        log.warn('%s already exists', pkg_info)
+        return
+
+    log.warn('Creating %s', pkg_info)
+    f = open(pkg_info, 'w')
+    try:
+        f.write(SETUPTOOLS_PKG_INFO)
+    finally:
+        f.close()
+
+    pth_file = os.path.join(placeholder, 'setuptools.pth')
+    log.warn('Creating %s', pth_file)
+    f = open(pth_file, 'w')
+    try:
+        f.write(os.path.join(os.curdir, setuptools_file))
+    finally:
+        f.close()
+
+_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
+    pkg_info = os.path.join(path, 'EGG-INFO', 'PKG-INFO')
+    if os.path.exists(pkg_info):
+        if _same_content(pkg_info, SETUPTOOLS_PKG_INFO):
+            log.warn('%s already patched.', pkg_info)
+            return False
+    _rename_path(path)
+    os.mkdir(path)
+    os.mkdir(os.path.join(path, 'EGG-INFO'))
+    pkg_info = os.path.join(path, 'EGG-INFO', 'PKG-INFO')
+    f = open(pkg_info, 'w')
+    try:
+        f.write(SETUPTOOLS_PKG_INFO)
+    finally:
+        f.close()
+    return True
+
+_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:]
+    for index, arg in enumerate(args):
+        for option in ('--root', '--prefix'):
+            if arg.startswith('%s=' % option):
+                top_dir = arg.split('root=')[-1]
+                return location.startswith(top_dir)
+            elif arg == option:
+                if len(args) > index:
+                    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 True
+
+
+def _fake_setuptools():
+    log.warn('Scanning installed packages')
+    try:
+        import pkg_resources
+    except ImportError:
+        # we're cool
+        log.warn('Setuptools or Distribute does not seem to be installed.')
+        return
+    ws = pkg_resources.working_set
+    try:
+        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'))
+
+    if setuptools_dist is None:
+        log.warn('No setuptools distribution found')
+        return
+    # detecting if it was already faked
+    setuptools_location = setuptools_dist.location
+    log.warn('Setuptools installation detected at %s', setuptools_location)
+
+    # if --root or --preix was provided, and if
+    # setuptools is not located in them, we don't patch it
+    if not _under_prefix(setuptools_location):
+        log.warn('Not patching, --root or --prefix is installing Distribute'
+                 ' in another location')
+        return
+
+    # let's see if its an egg
+    if not setuptools_location.endswith('.egg'):
+        log.warn('Non-egg installation')
+        res = _remove_flat_installation(setuptools_location)
+        if not res:
+            return
+    else:
+        log.warn('Egg installation')
+        pkg_info = os.path.join(setuptools_location, 'EGG-INFO', 'PKG-INFO')
+        if (os.path.exists(pkg_info) and
+            _same_content(pkg_info, SETUPTOOLS_PKG_INFO)):
+            log.warn('Already patched.')
+            return
+        log.warn('Patching...')
+        # let's create a fake egg replacing setuptools one
+        res = _patch_egg_dir(setuptools_location)
+        if not res:
+            return
+    log.warn('Patched done.')
+    _relaunch()
+
+
+def _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']:
+        sys.argv[0] = 'setup.py'
+    args = [sys.executable] + sys.argv
+    sys.exit(subprocess.call(args))
+
+
+def _extractall(self, path=".", members=None):
+    """Extract all members from the archive to the current working
+       directory and set owner, modification time and permissions on
+       directories afterwards. `path' specifies a different directory
+       to extract to. `members' is optional and must be a subset of the
+       list returned by getmembers().
+    """
+    import copy
+    import operator
+    from tarfile import ExtractError
+    directories = []
+
+    if members is None:
+        members = self
+
+    for tarinfo in members:
+        if tarinfo.isdir():
+            # Extract directories with a safe mode.
+            directories.append(tarinfo)
+            tarinfo = copy.copy(tarinfo)
+            tarinfo.mode = 448 # decimal for oct 0700
+        self.extract(tarinfo, path)
+
+    # Reverse sort directories.
+    if sys.version_info < (2, 4):
+        def sorter(dir1, dir2):
+            return cmp(dir1.name, dir2.name)
+        directories.sort(sorter)
+        directories.reverse()
+    else:
+        directories.sort(key=operator.attrgetter('name'), reverse=True)
+
+    # Set correct owner, mtime and filemode on directories.
+    for tarinfo in directories:
+        dirpath = os.path.join(path, tarinfo.name)
+        try:
+            self.chown(tarinfo, dirpath)
+            self.utime(tarinfo, dirpath)
+            self.chmod(tarinfo, dirpath)
+        except ExtractError:
+            e = sys.exc_info()[1]
+            if self.errorlevel > 1:
+                raise
+            else:
+                self._dbg(1, "tarfile: %s" % e)
+
+
+def main(argv, version=DEFAULT_VERSION):
+    """Install or upgrade setuptools and EasyInstall"""
+    tarball = download_setuptools()
+    _install(tarball)
+
+
+if __name__ == '__main__':
+    main(sys.argv[1:])
 
 PAPEROPT_a4      = -D latex_paper_size=a4
 PAPEROPT_letter  = -D latex_paper_size=letter
-ALLSPHINXOPTS = -d _build/doctrees $(PAPEROPT_$(PAPER)) \
-                $(SPHINXOPTS) $(O) .
+ALLSPHINXOPTS    = -d _build/doctrees $(PAPEROPT_$(PAPER)) \
+                   $(SPHINXOPTS) $(O) .
+I18NSPHINXOPTS   = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(O) .
 
 .PHONY: help clean html dirhtml singlehtml text man pickle json htmlhelp \
 	qthelp devhelp epub latex latexpdf changes linkcheck doctest
 	@echo "  epub       to make an epub file"
 	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
 	@echo "  latexpdf   to make LaTeX files and run pdflatex"
+	@echo "  texinfo    to make Texinfo files"
+	@echo "  info       to make Texinfo files and run them through makeinfo"
+	@echo "  gettext    to make PO message catalogs"
 	@echo "  changes    to make an overview over all changed/added/deprecated items"
 	@echo "  linkcheck  to check all external links for integrity"
 
 	make -C _build/latex all-pdf
 	@echo "pdflatex finished; the PDF files are in _build/latex."
 
+gettext:
+	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) _build/locale
+	@echo
+	@echo "Build finished. The message catalogs are in _build/locale."
+
 changes:
 	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) _build/changes
 	@echo
 
 doctest:
 	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) _build/doctest
+
+texinfo:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) _build/texinfo
+	@echo
+	@echo "Build finished. The Texinfo files are in _build/texinfo."
+	@echo "Run \`make' in that directory to run these through makeinfo" \
+	      "(use \`make info' here to do that automatically)."
+
+info:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) _build/texinfo
+	@echo "Running Texinfo files through makeinfo..."
+	make -C _build/texinfo info
+	@echo "makeinfo finished; the Info files are in _build/texinfo."
Added
New image

doc/_templates/index.html

   <p>
     Sphinx is a tool that makes it easy to create intelligent and beautiful
     documentation, written by Georg Brandl and licensed under the BSD license.</p>
-  <p>It was originally created for <a href="http://docs.python.org/dev/">the
+  <p>It was originally created for <a href="http://docs.python.org/">the
     new Python documentation</a>, and it has excellent facilities for the
     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

doc/_templates/indexsidebar.html

+<p class="logo"><a href="http://pocoo.org/">
+  <img src="{{ pathto("_static/pocoo.png", 1) }}" /></a></p>
+
 <h3>Download</h3>
 {% if version.endswith('(hg)') %}
 <p>This documentation is for version <b>{{ version }}</b>, which is
   <input type="text" name="email" value="your@email"/>
   <input type="submit" name="sub" value="Subscribe" />
 </form>
-<p>or come to the <tt>#python-docs</tt> channel on FreeNode.</p>
+<p>or come to the <tt>#pocoo</tt> channel on FreeNode.</p>
 <p>You can also open an issue at the
   <a href="http://www.bitbucket.org/birkenfeld/sphinx/issues/">tracker</a>.</p>
 
    .. versionadded:: 1.0
 
+
+.. module:: sphinx.builders.texinfo
+.. class:: TexinfoBuilder
+
+   This builder produces Texinfo files that can be processed into Info files by
+   the :program:`makeinfo` program.  You have to specify which documents are to
+   be included in which Texinfo files via the :confval:`texinfo_documents`
+   configuration value.
+
+   The Info format is the basis of the on-line help system used by GNU Emacs and
+   the terminal-based program :program:`info`.  See :ref:`texinfo-faq` for more
+   details.  The Texinfo format is the official documentation system used by the
+   GNU project.  More information on Texinfo can be found at
+   `<http://www.gnu.org/software/texinfo/>`_.
+
+   Its name is ``texinfo``.
+
+   .. versionadded:: 1.1
+
+
 .. currentmodule:: sphinx.builders.html
 .. class:: SerializingHTMLBuilder
 
 
    .. versionadded:: 0.5
 
+.. module:: sphinx.builders.gettext
+.. class:: MessageCatalogBuilder
+
+   This builder produces gettext-style message catalogs.  Each top-level file or
+   subdirectory grows a single ``.pot`` catalog template.
+
+   See the documentation on :ref:`intl` for further reference.
+
+   Its name is ``gettext``.
+
+   .. versionadded:: 1.1
+
 .. module:: sphinx.builders.changes
 .. class:: ChangesBuilder
 
 files.  They also copy the reST source files in the directory ``_sources``
 under the output directory.
 
-The :class:`PickleHTMLBuilder` is a builtin subclass that implements the pickle
+The :class:`.PickleHTMLBuilder` is a builtin subclass that implements the pickle
 serialization interface.
 
 The files per source file have the extensions of
-:attr:`~SerializingHTMLBuilder.out_suffix`, and are arranged in directories
+:attr:`~.SerializingHTMLBuilder.out_suffix`, and are arranged in directories
 just as the source files are.  They unserialize to a dictionary (or dictionary
 like structure) with these keys:
 
 
 The special files are located in the root output directory.  They are:
 
-:attr:`SerializingHTMLBuilder.globalcontext_filename`
+:attr:`.SerializingHTMLBuilder.globalcontext_filename`
    A pickled dict with these keys:
 
    ``project``, ``copyright``, ``release``, ``version``
    ``titles``
       A dictionary of all documents' titles, as HTML strings.
 
-:attr:`SerializingHTMLBuilder.searchindex_filename`
+:attr:`.SerializingHTMLBuilder.searchindex_filename`
    An index that can be used for searching the documentation.  It is a pickled
    list with these entries:
 
 exclude_patterns = ['_build']
 
 project = 'Sphinx'
-copyright = '2007-2010, Georg Brandl'
+copyright = '2007-2011, Georg Brandl'
 version = sphinx.__released__
 release = version
 show_authors = True
 html_theme = 'sphinxdoc'
 modindex_common_prefix = ['sphinx.']
 html_static_path = ['_static']
-html_index = 'index.html'
 html_sidebars = {'index': ['indexsidebar.html', 'searchbox.html']}
 html_additional_pages = {'index': 'index.html'}
 html_use_opensearch = 'http://sphinx.pocoo.org'
 latex_elements = {
     'fontpkg': '\\usepackage{palatino}',
 }
+latex_show_urls = 'footnote'
 
 autodoc_member_order = 'groupwise'
 todo_include_todos = True
      'template generator', '', 1),
 ]
 
+texinfo_documents = [
+    ('contents', 'sphinx', 'Sphinx Documentation', 'Georg Brandl',
+     'Sphinx', 'The Sphinx documentation builder.', 'Documentation tools',
+     1),
+]
+
+# We're not using intersphinx right now, but if we did, this would be part of
+# the mapping:
+intersphinx_mapping = {'python': ('http://docs.python.org/dev', None)}
+
 
 # -- Extension interface -------------------------------------------------------
 
 
 def setup(app):
     from sphinx.ext.autodoc import cut_lines
+    from sphinx.util.docfields import GroupedField
     app.connect('autodoc-process-docstring', cut_lines(4, what=['module']))
-    app.add_description_unit('confval', 'confval',
-                             objname='configuration value',
-                             indextemplate='pair: %s; configuration value')
-    app.add_description_unit('event', 'event', 'pair: %s; event', parse_event)
+    app.add_object_type('confval', 'confval',
+                        objname='configuration value',
+                        indextemplate='pair: %s; configuration value')
+    fdesc = GroupedField('parameter', label='Parameters',
+                         names=['param'], can_collapse=True)
+    app.add_object_type('event', 'event', 'pair: %s; event', parse_event,
+                        doc_field_types=[fdesc])
    Example patterns:
 
    - ``'library/xml.rst'`` -- ignores the ``library/xml.rst`` file (replaces
-     entry in :confval:`unused_docs`
+     entry in :confval:`unused_docs`)
    - ``'library/xml'`` -- ignores the ``library/xml`` directory (replaces entry
      in :confval:`exclude_trees`)
    - ``'library/xml*'`` -- ignores all files and directories starting with
    .. deprecated:: 1.0
       Use :confval:`exclude_patterns` instead.
 
-.. confval:: locale_dirs
-
-   .. versionadded:: 0.5
-
-   Directories in which to search for additional Sphinx message catalogs (see
-   :confval:`language`), relative to the source directory.  The directories on
-   this path are searched by the standard :mod:`gettext` module for a text
-   domain of ``sphinx``; so if you add the directory :file:`./locale` to this
-   settting, the message catalogs (compiled from ``.po`` format using
-   :program:`msgfmt`) must be in
-   :file:`./locale/{language}/LC_MESSAGES/sphinx.mo`.
-
-   The default is ``[]``.
-
 .. confval:: templates_path
 
    A list of paths that contain extra templates (or templates that overwrite
 
    .. versionadded:: 1.0
 
+.. confval:: nitpick_ignore
+
+   A list of ``(type, target)`` tuples (by default empty) that should be ignored
+   when generating warnings in "nitpicky mode".  Note that ``type`` should
+   include the domain name.  An example entry would be ``('py:func', 'int')``.
+
+   .. versionadded:: 1.1
+
 
 Project information
 -------------------
    If you don't need the separation provided between :confval:`version` and
    :confval:`release`, just set them both to the same value.
 
-.. confval:: language
-
-   The code for the language the docs are written in.  Any text automatically
-   generated by Sphinx will be in that language.  Also, in the LaTeX builder, a
-   suitable language will be selected as an option for the *Babel* package.
-   Default is ``None``, which means that no translation will be done.
-
-   .. versionadded:: 0.5
-
-   Currently supported languages are:
-
-   * ``ca`` -- Catalan
-   * ``cs`` -- Czech
-   * ``da`` -- Danish
-   * ``de`` -- German
-   * ``en`` -- English
-   * ``es`` -- Spanish
-   * ``fi`` -- Finnish
-   * ``fr`` -- French
-   * ``hr`` -- Croatian
-   * ``it`` -- Italian
-   * ``lt`` -- Lithuanian
-   * ``nl`` -- Dutch
-   * ``pl`` -- Polish
-   * ``pt_BR`` -- Brazilian Portuguese
-   * ``ru`` -- Russian
-   * ``sl`` -- Slovenian
-   * ``tr`` -- Turkish
-   * ``uk_UA`` -- Ukrainian
-   * ``zh_CN`` -- Simplified Chinese
-   * ``zh_TW`` -- Traditional Chinese
-
 .. confval:: today
              today_fmt
 
 
    A boolean that decides whether module names are prepended to all
    :term:`object` names (for object types where a "module" of some kind is
-   defined), e.g. for :rst:dir:`function` directives.  Default is ``True``.
+   defined), e.g. for :rst:dir:`py:function` directives.  Default is ``True``.
 
 .. confval:: show_authors
 
-   A boolean that decides whether :rst:dir:`moduleauthor` and :rst:dir:`sectionauthor`
-   directives produce any output in the built files.
+   A boolean that decides whether :rst:dir:`codeauthor` and
+   :rst:dir:`sectionauthor` directives produce any output in the built files.
 
 .. confval:: modindex_common_prefix
 
 .. confval:: trim_doctest_flags
 
    If true, doctest flags (comments looking like ``# doctest: FLAG, ...``) at
-   the ends of lines are removed for all code blocks showing interactive Python
-   sessions (i.e. doctests).  Default is true.  See the extension
-   :mod:`~sphinx.ext.doctest` for more possibilities of including doctests.
+   the ends of lines and ``<BLANKLINE>`` markers are removed for all code
+   blocks showing interactive Python sessions (i.e. doctests).  Default is
+   true.  See the extension :mod:`~sphinx.ext.doctest` for more possibilities
+   of including doctests.
 
    .. versionadded:: 1.0
+   .. versionchanged:: 1.1
+      Now also removes ``<BLANKLINE>``.
+
+
+.. _intl-options:
+
+Options for internationalization
+--------------------------------
+
+These options influence Sphinx' *Native Language Support*.  See the
+documentation on :ref:`intl` for details.
+
+.. confval:: language
+
+   The code for the language the docs are written in.  Any text automatically
+   generated by Sphinx will be in that language.  Also, Sphinx will try to
+   substitute individual paragraphs from your documents with the translation
+   sets obtained from :confval:`locale_dirs`.  In the LaTeX builder, a suitable
+   language will be selected as an option for the *Babel* package.  Default is
+   ``None``, which means that no translation will be done.
+
+   .. versionadded:: 0.5
+
+   Currently supported languages by Sphinx are:
+
+   * ``bn`` -- Bengali
+   * ``ca`` -- Catalan
+   * ``cs`` -- Czech
+   * ``da`` -- Danish
+   * ``de`` -- German
+   * ``en`` -- English
+   * ``es`` -- Spanish
+   * ``fa`` -- Iranian
+   * ``fi`` -- Finnish
+   * ``fr`` -- French
+   * ``hr`` -- Croatian
+   * ``it`` -- Italian
+   * ``ja`` -- Japanese
+   * ``lt`` -- Lithuanian
+   * ``nl`` -- Dutch
+   * ``pl`` -- Polish
+   * ``pt_BR`` -- Brazilian Portuguese
+   * ``ru`` -- Russian
+   * ``sl`` -- Slovenian
+   * ``sv`` -- Swedish
+   * ``tr`` -- Turkish
+   * ``uk_UA`` -- Ukrainian
+   * ``zh_CN`` -- Simplified Chinese
+   * ``zh_TW`` -- Traditional Chinese
+
+.. confval:: locale_dirs
+
+   .. versionadded:: 0.5
+
+   Directories in which to search for additional message catalogs (see
+   :confval:`language`), relative to the source directory.  The directories on
+   this path are searched by the standard :mod:`gettext` module.
+
+   Internal messages are fetched from a text domain of ``sphinx``; so if you
+   add the directory :file:`./locale` to this settting, the message catalogs
+   (compiled from ``.po`` format using :program:`msgfmt`) must be in
+   :file:`./locale/{language}/LC_MESSAGES/sphinx.mo`.  The text domain of
+   individual documents depends on their docname if they are top-level project
+   files and on their base directory otherwise.
+
+   The default is ``[]``.
 
 
 .. _html-options:
 
    .. versionadded:: 0.4
 
+.. confval:: html_context
+
+   A dictionary of values to pass into the template engine's context for all
+   pages.  Single values can also be put in this dictionary using the
+   :option:`-A` command-line option of ``sphinx-build``.
+
+   .. versionadded:: 0.5
+
 .. confval:: html_logo
 
    If given, this must be the name of an image file that is the logo of the
 
 .. confval:: html_add_permalinks
 
-   If true, Sphinx will add "permalinks" for each heading and description
-   environment as paragraph signs that become visible when the mouse hovers over
-   them.  Default: ``True``.
+   Sphinx will add "permalinks" for each heading and description environment as
+   paragraph signs that become visible when the mouse hovers over them.
+
+   This value determines the text for the permalink; it defaults to ``"¶"``.
+   Set it to ``None`` or the empty string to disable permalinks.
 
    .. versionadded:: 0.6
       Previously, this was always activated.
 
+   .. versionchanged:: 1.1
+      This can now be a string to select the actual text of the link.
+      Previously, only boolean values were accepted.
+
 .. confval:: html_sidebars
 
    Custom sidebar templates, must be a dictionary that maps document names to
    This will render the template ``customdownload.html`` as the page
    ``download.html``.
 
-   .. note::
-
-      Earlier versions of Sphinx had a value called :confval:`html_index` which
-      was a clumsy way of controlling the content of the "index" document.  If
-      you used this feature, migrate it by adding an ``'index'`` key to this
-      setting, with your custom template as the value, and in your custom
-      template, use ::
-
-         {% extend "defindex.html" %}
-         {% block tables %}
-         ... old template content ...
-         {% endblock %}
-
 .. confval:: html_domain_indices
 
    If true, generate domain-specific indices in addition to the general index.
 
    .. versionadded:: 1.0
 
+.. confval:: html_search_language
+
+   Language to be used for generating the HTML full-text search index.  This
+   defaults to the global language selected with :confval:`language`.  If there
+   is no support for this language, ``"en"`` is used which selects the English
+   language.
+
+   Support is present for these languages:
+
+   * ``en`` -- English
+   * ``ja`` -- Japanese
+
+   .. versionadded:: 1.1
+
+.. confval:: html_search_options
+
+   A dictionary with options for the search language support, empty by default.
+   The meaning of these options depends on the language selected.
+
+   The English support has no options.
+
+   The Japanese support has these options:
+
+   * ``type`` -- ``'mecab'`` or ``'default'`` (selects either MeCab or
+     TinySegmenter word splitter algorithm)
+   * ``dic_enc`` -- the encoding for the MeCab algorithm
+   * ``dict`` -- the dictionary to use for the MeCab algorithm
+   * ``lib`` -- the library name for finding the MeCab library via ctypes if the
+     Python binding is not installed
+
+   .. versionadded:: 1.1
+
 .. confval:: htmlhelp_basename
 
    Output file base name for HTML help builder.  Default is ``'pydoc'``.
 
    The default value is ``()``.
 
+   .. versionadded:: 1.1
+
 .. confval:: epub_pre_files
 
    Additional files that should be inserted before the text generated by
    a chapter, but can be confusing because it mixes entries of differnet
    depth in one list.  The default value is ``True``.
 
+
 .. confval:: epub_fix_images
 
    This flag determines if sphinx should try to fix image formats that are not
 
 .. confval:: latex_show_urls
 
-   If true, add URL addresses after links.  This is very useful for printed
-   copies of the manual.  Default is ``False``.
+   Control whether to display URL addresses.  This is very useful for printed
+   copies of the manual.  The setting can have the following values:
+
+   * ``'no'`` -- do not display URLs (default)
+   * ``'footnote'`` -- display URLs in footnotes
+   * ``'inline'`` -- display URLs inline in parentheses
 
    .. versionadded:: 1.0
+   .. versionchanged:: 1.1
+      This value is now a string; previously it was a boolean value, and a true
+      value selected the ``'inline'`` display.  For backwards compatibility,
+      ``True`` is still accepted.
 
 .. confval:: latex_elements
 
       Use the ``'pointsize'`` key in the :confval:`latex_elements` value.
 
 
+.. _text-options:
+
+Options for text output
+-----------------------
+
+These options influence text output.
+
+.. confval:: text_newlines
+
+   Determines which end-of-line character(s) are used in text output.
+
+   * ``'unix'``: use Unix-style line endings (``\n``)
+   * ``'windows'``: use Windows-style line endings (``\r\n``)
+   * ``'native'``: use the line ending style of the platform the documentation
+     is built on
+
+   Default: ``'unix'``.
+
+   .. versionadded:: 1.1
+
+.. confval:: text_sectionchars
+
+   A string of 7 characters that should be used for underlining sections.
+   The first character is used for first-level headings, the second for
+   second-level headings and so on.
+
+   The default is ``'*=-~"+`'``.
+
+   .. versionadded:: 1.1
+
+
 .. _man-options:
 
 Options for manual page output
      well as the name of the manual page (in the NAME section).
    * *description*: description of the manual page.  This is used in the NAME
      section.
-   * *authors*: A list of strings with authors, or a single string.  Can be
-     an empty string or list if you do not want to automatically generate
-     an AUTHORS section in the manual page.
+   * *authors*: A list of strings with authors, or a single string.  Can be an
+     empty string or list if you do not want to automatically generate an
+     AUTHORS section in the manual page.
    * *section*: The manual page section.  Used for the output file name as well
      as in the manual page header.
 
    .. versionadded:: 1.0
 
+.. confval:: man_show_urls
+
+   If true, add URL addresses after links.  Default is ``False``.
+
+   .. versionadded:: 1.1
+
+
+.. _texinfo-options:
+
+Options for Texinfo output