Commits

gbrandl  committed 40b842b Merge

merge with autosummary branch

  • Participants
  • Parent commits 5a20a3a, 82d567d

Comments (0)

Files changed (257)

 .*\.pyc
 .*\.egg
+.*\.so
 build/
 dist/
+tests/.coverage
+sphinx/pycode/Grammar.*pickle
 Sphinx.egg-info/
 doc/_build/
+TAGS
+83433c206e7f0d2a58243e2305f7253d172dce45 0.5
+dfe5aae7c8addea437d90fd3ba72f46ae8d95c53 0.5.1
-The doctools are written and maintained by Georg Brandl <georg@python.org>.
-Substantial parts of the templates and the web application were written by
-Armin Ronacher <armin.ronacher@active-4.com>.
+Sphinx is written and maintained by Georg Brandl <georg@python.org>.
 
-Other contributors are noted in the :copyright: fields within the docstrings
-of the respective files.
+Substantial parts of the templates were written by Armin Ronacher
+<armin.ronacher@active-4.com>.
+
+Other contributors, listed alphabetically, are:
+
+* Daniel Bültmann -- todo extension
+* Michael Droettboom -- inheritance_diagram extension
+* Charles Duffy -- original graphviz extension
+* Josip Dzolonga -- coverage builder
+* Horst Gutmann -- internationalization support
+* Martin Hans -- autodoc improvements
+* Dave Kuhlman -- original LaTeX writer
+* Thomas Lamb -- linkcheck builder
+* Will Maier -- directory HTML builder
+* Benjamin Peterson -- unittests
+* Stefan Seefeld -- toctree improvements
+* Antonio Valentino -- qthelp builder
+* Pauli Virtanen -- autodoc improvements
+* Sebastian Wiesner -- image handling, distutils support
 
 Many thanks for all contributions!
+
+There are also a few modules or functions incorporated from other
+authors and projects:
+
+* sphinx.util.jsdump uses the basestring encoding from simplejson,
+  written by Bob Ippolito, released under the MIT license
+* sphinx.util.stemmer was written by Vivake Gupta, placed in the
+  Public Domain
-Release 0.5 (in development)
+Release 0.6 (in development)
 ============================
 
 New features added
 ------------------
 
+* Incompatible changes:
+
+  - Templating now requires the Jinja2 library, which is an enhanced
+    version of the old Jinja1 engine.  Since the syntax and semantic
+    is largely the same, very few fixes should be necessary in
+    custom templates.
+
+  - The "document" div tag has been moved out of the ``layout.html``
+    template's "document" block, because the closing tag was already
+    outside.  If you overwrite this block, you need to remove your
+    "document" div tag as well.
+
+  - The ``autodoc_skip_member`` event now also gets to decide
+    whether to skip members whose name starts with underscores.
+    Previously, these members were always automatically skipped.
+    Therefore, if you handle this event, add something like this
+    to your event handler to restore the old behavior::
+
+       if name.startswith('_'):
+           return True
+
+* Theming support, see the new section in the documentation.
+
+* Markup:
+
+  - Due to popular demand, added a ``:doc:`` role which directly
+    links to another document without the need of creating a
+    label to which a ``:ref:`` could link to.
+
+  - #4: Added a ``:download:`` role that marks a non-document file
+    for inclusion into the HTML output and links to it.
+
+  - Added an ``only`` directive that can selectively include text
+    based on enabled "tags".  Tags can be given on the command
+    line.  Also, the current builder output format (e.g. "html" or
+    "latex") is always a defined tag.
+
+  - #10: Added HTML section numbers, enabled by giving a
+    ``:numbered:`` flag to the ``toctree`` directive.
+
+  - #114: Added an ``abbr`` role to markup abbreviations and
+    acronyms.
+
+  - The ``literalinclude`` directive now supports several more
+    options, to include only parts of a file.
+
+  - The ``toctree`` directive now supports a ``:hidden:`` flag,
+    which will prevent links from being generated in place of
+    the directive -- this allows you to define your document
+    structure, but place the links yourself.
+
+  - Paths to images, literal include files and download files
+    can now be absolute (like ``/images/foo.png``).  They are
+    treated as relative to the top source directory.
+
+  - #52: There is now a ``hlist`` directive, creating a compact
+    list by placing distributing items into multiple columns.
+
+  - #77: If a description environment with info field list only
+    contains one ``:param:`` entry, no bullet list is generated.
+
+  - #6: Don't generate redundant ``<ul>`` for top-level TOC tree
+    items, which leads to a visual separation of TOC entries.
+
+  - #23: Added a ``classmethod`` directive along with ``method``
+    and ``staticmethod``.
+
+  - Scaled images now get a link to the unscaled version.
+
+  - SVG images are now supported in HTML (via ``<object>`` and
+    ``<embed>`` tags).
+
+  - Added a ``toctree`` callable to the templates, and the ability
+    to include external links in toctrees. The 'collapse' keyword
+    argument indicates whether or not to only display subitems of
+    the current page.  (Defaults to True.)
+
+* Configuration:
+
+  - The new config value ``rst_epilog`` can contain reST that is
+    appended to each source file that is read.  This is the right
+    place for global substitutions.
+
+  - The new ``html_add_permalinks`` config value can be used to
+    switch off the generated "paragraph sign" permalinks for each
+    heading and definition environment.
+
+  - The new ``html_show_sourcelink`` config value can be used to
+    switch off the links to the reST sources in the sidebar.
+
+  - The default value for ``htmlhelp_basename`` is now the project
+    title, cleaned up as a filename.
+
+  - The new ``modindex_common_prefix`` config value can be used to
+    ignore certain package names for module index sorting.
+
+  - The new ``trim_footnote_reference_space`` config value mirrors
+    the docutils config value of the same name and removes the
+    space before a footnote reference that is necessary for reST
+    to recognize the reference.
+
+  - The new ``latex_additional_files`` config value can be used to
+    copy files (that Sphinx doesn't copy automatically, e.g. if they
+    are referenced in custom LaTeX added in ``latex_elements``) to
+    the build directory.
+
+* Builders:
+
+  - The HTML builder now stores a small file named ``.buildinfo`` in
+    its output directory.  It stores a hash of config values that
+    can be used to determine if a full rebuild needs to be done (e.g.
+    after changing ``html_theme``).
+
+  - New builder for Qt help collections, by Antonio Valentino.
+
+  - The new ``DirectoryHTMLBuilder`` (short name ``dirhtml``) creates
+    a separate directory for every page, and places the page there
+    in a file called ``index.html``.  Therefore, page URLs and links
+    don't need to contain ``.html``.
+
+  - The new ``html_link_suffix`` config value can be used to select
+    the suffix of generated links between HTML files.
+
+  - #96: The LaTeX builder now supports figures wrapped by text, when
+    using the ``figwidth`` option and right/left alignment.
+
+* New translations:
+  
+  - Italian by Sandro Dentella.
+
+  - Ukrainian by Petro Sasnyk.
+
+  - Finnish by Jukka Inkeri.
+
+* Extensions and API:
+
+  - New ``graphviz`` extension to embed graphviz graphs.
+
+  - New ``inheritance_diagram`` extension to embed... inheritance
+    diagrams!
+
+  - Autodoc now has a reusable Python API, which can be used to
+    create custom types of objects to auto-document (e.g. Zope
+    interfaces).  See also ``Sphinx.add_autodocumenter()``.
+
+  - Autodoc now handles documented attributes.
+
+  - Autodoc now handles inner classes and their methods.
+
+  - Autodoc can document classes as functions now if explicitly
+    marked with `autofunction`.
+
+  - Autodoc can now order members either alphabetically (like
+    previously) or by member type; configurable either with the
+    config value ``autodoc_member_order`` or a ``member-order``
+    option per directive.
+
+  - The function ``Sphinx.add_directive()`` now also supports
+    docutils 0.5-style directive classes.  If they inherit from
+    ``sphinx.util.compat.Directive``, they also work with
+    docutils 0.4.
+
+  - There is now a ``Sphinx.add_lexer()`` method to be able to use
+    custom Pygments lexers easily.
+
+  - There is now ``Sphinx.add_generic_role()`` to mirror the
+    docutils' own function.
+
+* Other changes:
+
+  - Config overrides for single dict keys can now be given on the
+    command line.
+
+  - There is now a ``doctest_global_setup`` config value that can
+    be used to give setup code for all doctests in the documentation.
+
+  - Source links in HTML are now generated with ``rel="nofollow"``.
+
+  - Quickstart can now generate a Windows ``make.bat`` file.
+
+  - #62: There is now a ``-w`` option for sphinx-build that writes
+    warnings to a file, in addition to stderr.
+
+  - There is now a ``-W`` option for sphinx-build that turns warnings
+    into errors.
+
+
+Release 0.5.2 (in development)
+==============================
+
+* Properly escape ``|`` in LaTeX output.
+
+* #71: If a decoding error occurs in source files, print a
+  warning and replace the characters by "?".
+
+* Fix a problem in the HTML search if the index takes too long
+  to load.
+
+* Don't output system messages while resolving, because they
+  would stay in the doctrees even if keep_warnings is false.
+
+* #82: Determine the correct path for dependencies noted by
+  docutils.  This fixes behavior where a source with dependent
+  files was always reported as changed.
+
+* Recognize toctree directives that are not on section toplevel,
+  but within block items, such as tables.
+
+* Use a new RFC base URL, since rfc.org seems down.
+
+* Fix a crash in the todolist directive when no todo items are
+  defined.
+
+* Don't call LaTeX or dvipng over and over again if it was not
+  found once, and use text-only latex as a substitute in that case.
+
+* Fix problems with footnotes in the LaTeX output.
+
+* Prevent double hyphens becoming en-dashes in literal code in
+  the LaTeX output.
+
+* Open literalinclude files in universal newline mode to allow
+  arbitrary newline conventions.
+
+* Actually make the ``-Q`` option work.
+
+* #86: Fix explicit document titles in toctrees.
+
+* #81: Write environment and search index in a manner that is safe
+  from exceptions that occur during dumping.
+
+* #80: Fix UnicodeErrors when a locale is set with setlocale().
+
+
+Release 0.5.1 (Dec 15, 2008)
+============================
+
+* #67: Output warnings about failed doctests in the doctest extension
+  even when running in quiet mode.
+
+* #72: In pngmath, make it possible to give a full path to LaTeX and
+  dvipng on Windows.  For that to work, the ``pngmath_latex`` and
+  ``pngmath_dvipng`` options are no longer split into command and
+  additional arguments; use ``pngmath_latex_args`` and
+  ``pngmath_dvipng_args`` to give additional arguments.
+
+* Don't crash on failing doctests with non-ASCII characters.
+
+* Don't crash on writing status messages and warnings containing
+  unencodable characters.
+
+* Warn if a doctest extension block doesn't contain any code.
+
+* Fix the handling of ``:param:`` and ``:type:`` doc fields when
+  they contain markup (especially cross-referencing roles).
+
+* #65: Fix storage of depth information for PNGs generated by the
+  pngmath extension.
+
+* Fix autodoc crash when automethod is used outside a class context.
+
+* #68: Fix LaTeX writer output for images with specified height.
+
+* #60: Fix wrong generated image path when including images in sources
+  in subdirectories.
+
+* Fix the JavaScript search when html_copy_source is off.
+
+* Fix an indentation problem in autodoc when documenting classes
+  with the option ``autoclass_content = "both"`` set.
+
+* Don't crash on empty index entries, only emit a warning.
+
+* Fix a typo in the search JavaScript code, leading to unusable
+  search function in some setups.
+
+
+Release 0.5 (Nov 23, 2008) -- Birthday release!
+===============================================
+
+New features added
+------------------
+
 * Markup features:
 
   - Citations are now global: all citation defined in any file can be
   - The ``seealso`` directive can now also be given arguments, as a short
     form.
 
+  - You can now document several programs and their options with the
+    new ``program`` directive.
+
 * HTML output and templates:
 
   - Incompatible change: The "root" relation link (top left in the
   - The JavaScript search now searches for objects before searching in
     the full text.
 
+  - TOC tree entries now have CSS classes that make it possible to
+    style them depending on their depth.
+
+  - Highlighted code blocks now have CSS classes that make it possible
+    to style them depending on their language.
+
   - HTML ``<meta>`` tags via the docutils ``meta`` directive are now
     supported.
 
     * Michał Kandulski -- Polish
     * Yasushi Masuda -- Japanese
     * Guillem Borrell -- Spanish
+    * Luc Saffre and Peter Bertels -- Dutch
+    * Fred Lin -- Traditional Chinese
+    * Roger Demetrescu -- Brazilian Portuguese
+    * Rok Garbas -- Slovenian
 
   - The new config value ``highlight_language`` set a global default for
     highlighting.  When ``'python3'`` is selected, console output blocks
     creates links to Sphinx documentation of Python objects in other
     projects.
 
+  - The new extension ``sphinx.ext.todo`` allows the insertion of
+    "To do" directives whose visibility in the output can be toggled.
+    It also adds a directive to compile a list of all todo items.
+
   - sphinx.ext.autodoc has a new event ``autodoc-process-signature``
     that allows tuning function signature introspection.
 
     default HTML template.
 
   - Added new events: ``source-read``, ``env-updated``,
-    ``missing-reference``, ``build-finished``.
+    ``env-purge-doc``, ``missing-reference``, ``build-finished``.
 
 * Other changes:
 
   - Added a command-line switch ``-A``: it can be used to supply
     additional values into the HTML templates.
 
+  - Added a command-line switch ``-C``: if it is given, no configuration
+    file ``conf.py`` is required.
+
   - Added a distutils command `build_sphinx`: When Sphinx is installed,
     you can call ``python setup.py build_sphinx`` for projects that have
     Sphinx documentation, which will build the docs and place them in
 Bugs fixed
 ----------
 
-* Support option lists in the text writer.  Make sure that dashes
+* #51: Escape configuration values placed in HTML templates.
+
+* #44: Fix small problems in HTML help index generation.
+
+* Fix LaTeX output for line blocks in tables.
+
+* #38: Fix "illegal unit" error when using pixel image widths/heights.
+
+* Support table captions in LaTeX output.
+
+* #39: Work around a bug in Jinja that caused "<generator ...>" to be
+  emitted in HTML output.
+
+* Fix a problem with module links not being generated in LaTeX output.
+
+* Fix the handling of images in different directories.
+
+* #29: Support option lists in the text writer.  Make sure that dashes
   introducing long option names are not contracted to en-dashes.
 
 * Support the "scale" option for images in HTML output.
 
-* Properly escape quotes in HTML help attribute values.
+* #25: Properly escape quotes in HTML help attribute values.
 
 * Fix LaTeX build for some description environments with ``:noindex:``.
 
-* Don't crash on weird casing of role names (like ``:Class:``).
+* #24: Don't crash on uncommon casing of role names (like ``:Class:``).
 
 * Only output ANSI colors on color terminals.
 
 Projects using Sphinx
 =====================
 
-This is an (incomplete) 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
+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>`_.
 
+* APSW: http://apsw.googlecode.com/svn/publish/index.html
+* boostmpi: http://documen.tician.de/boostmpi/
+* Calibre: http://calibre.kovidgoyal.net/user_manual/
+* Chaco: http://code.enthought.com/projects/chaco/docs/html/
+* 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/
+* Django: http://docs.djangoproject.com/
+* F2py: http://www.f2py.org/html/
+* GeoDjango: http://geodjango.org/docs/
+* Glashammer: http://glashammer.org/
+* Grok: http://grok.zope.org/doc/current/
+* Hedge: http://documen.tician.de/hedge/
+* IFM: http://fluffybunny.memebot.com/ifm-docs/index.html
+* Jinja: http://jinja.pocoo.org/2/documentation/
+* MapServer: http://mapserver.osgeo.org/
+* Matplotlib: http://matplotlib.sourceforge.net/
+* Mayavi: http://code.enthought.com/projects/mayavi/docs/development/html/mayavi
+* MeshPy: http://documen.tician.de/meshpy/
+* Mixin.com: http://dev.mixin.com/
+* mpmath: http://mpmath.googlecode.com/svn/trunk/doc/build/index.html
+* MyHDL: http://www.myhdl.org/doc/0.6/
+* NetworkX: http://networkx.lanl.gov/
+* NumPy: http://docs.scipy.org/doc/numpy/reference/
+* ObjectListView: http://objectlistview.sourceforge.net/python
+* OpenLayers: http://docs.openlayers.org/
+* openWNS: http://docs.openwns.org/
+* Paste: http://pythonpaste.org/script/
+* Paver: http://www.blueskyonmars.com/projects/paver/
+* Py on Windows: http://timgolden.me.uk/python-on-windows/
+* PyCuda: http://documen.tician.de/pycuda/
+* PyEphem: http://rhodesmill.org/pyephem/
+* Pyevolve: http://pyevolve.sourceforge.net/
+* PyLit: http://pylit.berlios.de/
+* Pylo: http://documen.tician.de/pylo/
+* Pylons: http://docs.pylonshq.com/
+* PyMOTW: http://www.doughellmann.com/PyMOTW/
+* PyPubSub: http://pubsub.sourceforge.net/
+* pyrticle: http://documen.tician.de/pyrticle/
+* Pysparse: http://pysparse.sourceforge.net/
+* Python: http://docs.python.org/
+* python-apt: http://people.debian.org/~jak/python-apt-doc/
+* PyUblas: http://documen.tician.de/pyublas/
+* Quex: http://quex.sourceforge.net/
+* Reteisi: http://docs.argolinux.org/reteisi/
+* Roundup: http://www.roundup-tracker.org/
+* Satchmo: http://www.satchmoproject.com/docs/svn/
+* Scapy: http://www.secdev.org/projects/scapy/doc/
+* Self: http://selflanguage.org/
+* SimPy: http://simpy.sourceforge.net/
 * Sphinx: http://sphinx.pocoo.org/
-* Python: http://docs.python.org/dev/
-* NumPy: http://mentat.za.net/numpy/refguide/
-* Matplotlib: http://matplotlib.sourceforge.net/
-* Pylons: http://docs.pylonshq.com/
-* Django: http://docs.djangoproject.com/
-* Grok: http://grok.zope.org/doc/current/
+* Sprox: http://sprox.org/
+* SQLAlchemy: http://www.sqlalchemy.org/docs/
+* Sqlkit: http://sqlkit.argolinux.org/
+* SymPy: http://docs.sympy.org/
+* tinyTiM: http://tinytim.sourceforge.net/docs/2.0/
 * TurboGears: http://turbogears.org/2.0/docs/
-* Jinja: http://jinja.pocoo.org/2/documentation/
-* Cython: http://docs.cython.org/
-* F2py: http://www.f2py.org/html/
+* VOR: http://www.vor-cycling.be/
+* WFront: http://discorporate.us/projects/WFront/
+* WTForms: http://wtforms.simplecodes.com/docs/
+* Zope 3: e.g. http://docs.carduner.net/z3c-tutorial/
 * zc.async: http://packages.python.org/zc.async/1.5.0/
-* Mayavi: http://code.enthought.com/projects/mayavi/docs/development/html/mayavi
-* Chaco: http://code.enthought.com/projects/chaco/docs/html/
-* Paver: http://www.blueskyonmars.com/projects/paver/
-* Satchmo: http://www.satchmoproject.com/docs/svn/
-* PyEphem: http://rhodesmill.org/pyephem/
-* Paste: http://pythonpaste.org/script/
-* Director: http://packages.python.org/director/
-* Calibre: http://calibre.kovidgoyal.net/user_manual/
-* PyUblas: http://tiker.net/doc/pyublas/
-* Py on Windows: http://timgolden.me.uk/python-on-windows/
-* mpmath: http://mpmath.googlecode.com/svn/trunk/doc/build/index.html
-* Zope 3: e.g. http://docs.carduner.net/z3c-tutorial/
-* Glashammer: http://glashammer.org/
-* SymPy: http://docs.sympy.org/
-* GeoDjango: http://geodjango.org/docs/
-* Mixin.com: http://dev.mixin.com/
-* PyPubSub: http://pubsub.sourceforge.net/
-Copyright (c) 2007-2008 by the respective authors (see AUTHORS file).
-All rights reserved.
-
-Redistribution and use in source and binary forms, with or without
-modification, are permitted provided that the following conditions are
-met:
-
-    * Redistributions of source code must retain the above copyright
-      notice, this list of conditions and the following disclaimer.
-
-    * Redistributions in binary form must reproduce the above
-      copyright notice, this list of conditions and the following
-      disclaimer in the documentation and/or other materials provided
-      with the distribution.
-
-    * The names of the contributors may not be used to endorse or
-      promote products derived from this software without specific
-      prior written permission.
-
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
-"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
-LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
-A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
-OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
-SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
-LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
-DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
-THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
-(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
-OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+License for Sphinx
+==================
+
+Copyright (c) 2007-2009 by the Sphinx team (see AUTHORS file).
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+* Redistributions of source code must retain the above copyright
+  notice, this list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright
+  notice, this list of conditions and the following disclaimer in the
+  documentation and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+
+Licenses for incorporated software
+==================================
+
+The pgen2 package, included in this distribution under the name
+sphinx.pycode.pgen2, is available in the Python 2.6 distribution under
+the PSF license agreement for Python:
+
+----------------------------------------------------------------------
+Copyright © 2001-2008 Python Software Foundation; All Rights Reserved.
+
+PYTHON SOFTWARE FOUNDATION LICENSE VERSION 2
+--------------------------------------------
+
+1. This LICENSE AGREEMENT is between the Python Software Foundation
+   ("PSF"), and the Individual or Organization ("Licensee") accessing
+   and otherwise using Python 2.6 software in source or binary form
+   and its associated documentation.
+
+2. Subject to the terms and conditions of this License Agreement, PSF
+   hereby grants Licensee a nonexclusive, royalty-free, world-wide
+   license to reproduce, analyze, test, perform and/or display
+   publicly, prepare derivative works, distribute, and otherwise use
+   Python 2.6 alone or in any derivative version, provided, however,
+   that PSF's License Agreement and PSF's notice of copyright, i.e.,
+   "Copyright © 2001-2008 Python Software Foundation; All Rights
+   Reserved" are retained in Python 2.6 alone or in any derivative
+   version prepared by Licensee.
+
+3. In the event Licensee prepares a derivative work that is based on
+   or incorporates Python 2.6 or any part thereof, and wants to make
+   the derivative work available to others as provided herein, then
+   Licensee hereby agrees to include in any such work a brief summary
+   of the changes made to Python 2.6.
+
+4. PSF is making Python 2.6 available to Licensee on an "AS IS" basis.
+   PSF MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED.  BY
+   WAY OF EXAMPLE, BUT NOT LIMITATION, PSF MAKES NO AND DISCLAIMS ANY
+   REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS FOR ANY
+   PARTICULAR PURPOSE OR THAT THE USE OF PYTHON 2.6 WILL NOT INFRINGE
+   ANY THIRD PARTY RIGHTS.
+
+5. PSF SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF PYTHON
+   2.6 FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS
+   AS A RESULT OF MODIFYING, DISTRIBUTING, OR OTHERWISE USING PYTHON
+   2.6, OR ANY DERIVATIVE THEREOF, EVEN IF ADVISED OF THE POSSIBILITY
+   THEREOF.
+
+6. This License Agreement will automatically terminate upon a material
+   breach of its terms and conditions.
+
+7. Nothing in this License Agreement shall be deemed to create any
+   relationship of agency, partnership, or joint venture between PSF
+   and Licensee.  This License Agreement does not grant permission to
+   use PSF trademarks or trade name in a trademark sense to endorse or
+   promote products or services of Licensee, or any third party.
+
+8. By copying, installing or otherwise using Python 2.6, Licensee
+   agrees to be bound by the terms and conditions of this License
+   Agreement.
+----------------------------------------------------------------------
+
+The included smartypants module, included as sphinx.util.smartypants,
+is available under the following license:
+
+----------------------------------------------------------------------
+SmartyPants_ license::
+
+    Copyright (c) 2003 John Gruber
+    (http://daringfireball.net/)
+    All rights reserved.
+
+    Redistribution and use in source and binary forms, with or without
+    modification, are permitted provided that the following conditions
+    are met:
+
+    *   Redistributions of source code must retain the above copyright
+        notice, this list of conditions and the following disclaimer.
+
+    *   Redistributions in binary form must reproduce the above
+        copyright notice, this list of conditions and the following
+        disclaimer in the documentation and/or other materials
+        provided with the distribution.
+
+    *   Neither the name "SmartyPants" nor the names of its
+        contributors may be used to endorse or promote products
+        derived from this software without specific prior written
+        permission.
+
+    This software is provided by the copyright holders and
+    contributors "as is" and any express or implied warranties,
+    including, but not limited to, the implied warranties of
+    merchantability and fitness for a particular purpose are
+    disclaimed. In no event shall the copyright owner or contributors
+    be liable for any direct, indirect, incidental, special,
+    exemplary, or consequential damages (including, but not limited
+    to, procurement of substitute goods or services; loss of use,
+    data, or profits; or business interruption) however caused and on
+    any theory of liability, whether in contract, strict liability, or
+    tort (including negligence or otherwise) arising in any way out of
+    the use of this software, even if advised of the possibility of
+    such damage.
+
+
+smartypants.py license::
+
+    smartypants.py is a derivative work of SmartyPants.
+
+    Redistribution and use in source and binary forms, with or without
+    modification, are permitted provided that the following conditions
+    are met:
+
+    *   Redistributions of source code must retain the above copyright
+        notice, this list of conditions and the following disclaimer.
+
+    *   Redistributions in binary form must reproduce the above
+        copyright notice, this list of conditions and the following
+        disclaimer in the documentation and/or other materials
+        provided with the distribution.
+
+    This software is provided by the copyright holders and
+    contributors "as is" and any express or implied warranties,
+    including, but not limited to, the implied warranties of
+    merchantability and fitness for a particular purpose are
+    disclaimed. In no event shall the copyright owner or contributors
+    be liable for any direct, indirect, incidental, special,
+    exemplary, or consequential damages (including, but not limited
+    to, procurement of substitute goods or services; loss of use,
+    data, or profits; or business interruption) however caused and on
+    any theory of liability, whether in contract, strict liability, or
+    tort (including negligence or otherwise) arising in any way out of
+    the use of this software, even if advised of the possibility of
+    such damage.
+----------------------------------------------------------------------
+
+The ElementTree package, included in this distribution in
+test/etree13, is available under the following license:
+
+----------------------------------------------------------------------
+The ElementTree toolkit is
+
+Copyright (c) 1999-2007 by Fredrik Lundh
+
+By obtaining, using, and/or copying this software and/or its
+associated documentation, you agree that you have read, understood,
+and will comply with the following terms and conditions:
+
+Permission to use, copy, modify, and distribute this software and its
+associated documentation for any purpose and without fee is hereby
+granted, provided that the above copyright notice appears in all
+copies, and that both that copyright notice and this permission notice
+appear in supporting documentation, and that the name of Secret Labs
+AB or the author not be used in advertising or publicity pertaining to
+distribution of the software without specific, written prior
+permission.
+
+SECRET LABS AB AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO
+THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANT- ABILITY
+AND FITNESS.  IN NO EVENT SHALL SECRET LABS AB OR THE AUTHOR BE LIABLE
+FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
+OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+----------------------------------------------------------------------
+
+The included JQuery JavaScript library is available under the MIT
+license:
+
+----------------------------------------------------------------------
+Copyright (c) 2008 John Resig, http://jquery.com/
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+----------------------------------------------------------------------
 include sphinx-quickstart.py
 
 recursive-include sphinx/texinputs *
-recursive-include sphinx/templates *.html *.xml
-recursive-include sphinx/static *
+recursive-include sphinx/themes *
 recursive-include sphinx/locale *
 recursive-include tests *
 recursive-include utils *
+include sphinx/pycode/Grammar.txt
 
 recursive-include doc *
 prune doc/_build
 all: clean-pyc check test
 
 check:
-	@$(PYTHON) utils/check_sources.py -i sphinx/style/jquery.js sphinx
+	@$(PYTHON) utils/check_sources.py -i sphinx/style/jquery.js \
+		-i sphinx/pycode/pgen2 -i sphinx/util/smartypants.py \
+		-i doc/_build -i ez_setup.py -i tests/path.py .
 
 clean: clean-pyc clean-patchfiles
 
 
 test:
 	@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)
+.. -*- restructuredtext -*-
+
 =================
 README for Sphinx
 =================
 After installing::
 
    cd doc
-   mkdir -p _build/html
    sphinx-build . _build/html
-   browser _build/index.html
+
+Then, direct your browser to ``_build/html/index.html``.
 
 Or read them online at <http://sphinx.pocoo.org/>.
 
 Contributing
 ============
 
-Send wishes, comments, patches, etc. to georg@python.org.
+Send wishes, comments, patches, etc. to sphinx-dev@googlegroups.com.
-[extractors]
-jinja = sphinx._jinja.babel_extract
 [python: **.py]
-[jinja: **/templates/**.html]
-[jinja: **/templates/**.xml]
+[jinja2: **/templates/**.html]
+[jinja2: **/templates/**.xml]
 [javascript: **.js]

File doc/Makefile

 ALLSPHINXOPTS = -d _build/doctrees $(PAPEROPT_$(PAPER)) \
                 $(SPHINXOPTS) .
 
-.PHONY: help clean html web htmlhelp latex changes linkcheck
+.PHONY: help clean html dirhtml pickle htmlhelp qthelp latex changes linkcheck doctest
 
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
 	@echo "  html      to make standalone HTML files"
-	@echo "  web       to make files usable by Sphinx.web"
+	@echo "  dirhtml   to make HTML files called index.html in directories"
+	@echo "  pickle    to make pickle files"
 	@echo "  htmlhelp  to make HTML files and a HTML help project"
 	@echo "  latex     to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
 	@echo "  changes   to make an overview over all changed/added/deprecated items"
 	@echo
 	@echo "Build finished. The HTML pages are in _build/html."
 
+dirhtml:
+	mkdir -p _build/dirhtml _build/doctrees
+	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) _build/dirhtml
+	@echo
+	@echo "Build finished. The HTML pages are in _build/dirhtml."
+
+text:
+	mkdir -p _build/text _build/doctrees
+	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) _build/text
+	@echo
+	@echo "Build finished."
+
 pickle:
 	mkdir -p _build/pickle _build/doctrees
 	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) _build/pickle
-	@echo
-	@echo "Build finished; now you can run"
-	@echo "  python -m sphinx.web _build/pickle"
-	@echo "to start the server."
 
 htmlhelp:
 	mkdir -p _build/htmlhelp _build/doctrees
 	@echo "Build finished; now you can run HTML Help Workshop with the" \
 	      ".hhp project file in _build/htmlhelp."
 
+qthelp:
+	mkdir -p _build/qthelp _build/doctrees
+	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) _build/qthelp
+	@echo
+	@echo "Build finished; now you can run qcollectiongenerator with the" \
+	      ".qhcp project file in build/qthelp."
+	@echo "# qcollectiongenerator _build/qthelp/Sphinx.qhcp"
+	@echo "To view the help collection:"
+	@echo "# assistant -collectionFile _build/qthelp/Sphinx.qhc"
+
 latex:
 	mkdir -p _build/latex _build/doctrees
 	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) _build/latex

File doc/_templates/index.html

 {% block body %}
   <h1>Welcome</h1>
 
+  <div class="quotebar">
+    <p>What users say:</p>
+    <p>&ldquo;Cheers for a great tool that actually makes programmers <b>want</b>
+      to write documentation!&rdquo;</p>
+  </div>
+
   <p>
     Sphinx is a tool that makes it easy to create intelligent and beautiful
-    documentation for Python projects, written by Georg Brandl and licensed
-    under the BSD license.</p>
+    documentation, written by Georg Brandl and licensed under the BSD license.</p>
   <p>It was originally created to translate <a href="http://docs.python.org/dev/">the
-    new Python documentation</a>, but has now been cleaned up in the hope that
-    it will be useful to many other projects.  (Of course, this site is also
-    created from reStructuredText sources using Sphinx!)
+    new Python documentation</a>, and it has excellent support for the documentation
+    of Python projects, but other documents can be written with it too.  Of course,
+    this site is also created from reStructuredText sources using Sphinx!
   </p>
   <p>
-    Although it is still under constant development, the following features are
+    It is still under constant development, and the following features are
     already present, work fine and can be seen &#8220;in action&#8221; in the
     Python docs:
   </p>
   </p>
   <p>The code can be found in a Mercurial repository, at
     <tt>http://bitbucket.org/birkenfeld/sphinx/</tt>.</p>
-  
+
 {% endblock %}

File doc/_templates/indexsidebar.html

 <p>Current version: <b>{{ version }}</b></p>
 <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 Sphinx</pre>
+<pre>easy_install -U Sphinx</pre>
 {% endif %}
 
 <h3>Questions? Suggestions?</h3>
 </form>
 <p>or come to the <tt>#python-docs</tt> channel on FreeNode.</p>
 <p>You can also open an issue at the
-  <a href="http://code.google.com/p/sphinx/issues/list">tracker</a>.</p>
+  <a href="http://www.bitbucket.org/birkenfeld/sphinx/issues/">tracker</a>.</p>

File doc/_templates/layout.html

 {% extends "!layout.html" %}
 
 {% block rootrellink %}
-        <li><a href="{{ pathto('index') }}">Sphinx home </a> |&nbsp;</li>
-        <li><a href="{{ pathto('contents') }}">Documentation </a> &raquo;</li>
+        <li><a href="{{ pathto('index') }}">Sphinx home</a>&nbsp;|&nbsp;</li>
+        <li><a href="{{ pathto('contents') }}">Documentation</a>&raquo;</li>
 {% endblock %}
 
-{% block relbar1 %}
+{% 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>
-{{ super() }}
 {% endblock %}
-
-{# put the sidebar before the body #}
-{% block sidebar1 %}{{ sidebar() }}{% endblock %}
-{% block sidebar2 %}{% endblock %}

File doc/builders.rst

 Available builders
 ==================
 
-.. module:: sphinx.builder
+.. module:: sphinx.builders
    :synopsis: Available built-in builder classes.
 
 These are the built-in Sphinx builders.  More builders can be added by
 :program:`sphinx-build` to select a builder.
 
 
+.. module:: sphinx.builders.html
 .. class:: StandaloneHTMLBuilder
 
    This is the standard HTML builder.  Its output is a directory with HTML
 
    Its name is ``html``.
 
+.. class:: DirectoryHTMLBuilder
+
+   This is a subclass of the standard HTML builder.  Its output is a directory
+   with HTML files, where each file is called ``index.html`` and placed in a
+   subdirectory named like its page name.  For example, the document
+   ``markup/rest.rst`` will not result in an output file ``markup/rest.html``,
+   but ``markup/rest/index.html``.  When generating links between pages, the
+   ``index.html`` is omitted, so that the URL would look like ``markup/rest/``.
+
+   Its name is ``dirhtml``.
+
+   .. versionadded:: 0.6
+
 .. class:: HTMLHelpBuilder
 
    This builder produces the same output as the standalone HTML builder, but
    also generates HTML Help support files that allow the Microsoft HTML Help
    Workshop to compile them into a CHM file.
 
-   Its name is ``htmlhelp``. 
+   Its name is ``htmlhelp``.
+
+.. module:: sphinx.builders.latex
+.. class:: LaTeXBuilder
+
+   This builder produces a bunch of LaTeX files in the output directory.  You
+   have to specify which documents are to be included in which LaTeX files via
+   the :confval:`latex_documents` configuration value.  There are a few
+   configuration values that customize the output of this builder, see the
+   chapter :ref:`latex-options` for details.
+
+   .. note::
+
+      The produced LaTeX file uses several LaTeX packages that may not be
+      present in a "minimal" TeX distribution installation.  For TeXLive,
+      the following packages need to be installed:
+
+      * latex-recommended
+      * latex-extra
+      * fonts-recommended
+
+   Its name is ``latex``.
+
+.. module:: sphinx.builders.text
+.. class:: TextBuilder
+
+   This builder produces a text file for each reST file -- this is almost the
+   same as the reST source, but with much of the markup stripped for better
+   readability.
+
+   Its name is ``text``.
+
+   .. versionadded:: 0.4
+
+.. currentmodule:: sphinx.builders.html
+.. class:: SerializingHTMLBuilder
+
+   This builder uses a module that implements the Python serialization API
+   (`pickle`, `simplejson`, `phpserialize`, and others) to dump the generated
+   HTML documentation.  The pickle builder is a subclass of it.
+
+   A concreate subclass of this builder serializing to the `PHP serialization`_
+   format could look like this::
+
+        import phpserialize
+
+        class PHPSerializedBuilder(SerializingHTMLBuilder):
+            name = 'phpserialized'
+            implementation = phpserialize
+            out_suffix = '.file.phpdump'
+            globalcontext_filename = 'globalcontext.phpdump'
+            searchindex_filename = 'searchindex.phpdump'
+
+   .. _PHP serialization: http://pypi.python.org/pypi/phpserialize
+
+   .. attribute:: implementation
+
+      A module that implements `dump()`, `load()`, `dumps()` and `loads()`
+      functions that conform to the functions with the same names from the
+      pickle module.  Known modules implementing this interface are
+      `simplejson` (or `json` in Python 2.6), `phpserialize`, `plistlib`,
+      and others.
+
+   .. attribute:: out_suffix
+
+      The suffix for all regular files.
+
+   .. attribute:: globalcontext_filename
+
+      The filename for the file that contains the "global context".  This
+      is a dict with some general configuration values such as the name
+      of the project.
+
+   .. attribute:: searchindex_filename
+
+      The filename for the search index Sphinx generates.
+
+
+   See :ref:`serialization-details` for details about the output format.
+
+   .. versionadded:: 0.5
 
 .. class:: PickleHTMLBuilder
 
 
    .. versionadded:: 0.5
 
-.. class:: LaTeXBuilder
-
-   This builder produces a bunch of LaTeX files in the output directory.  You
-   have to specify which documents are to be included in which LaTeX files via
-   the :confval:`latex_documents` configuration value.  There are a few
-   configuration values that customize the output of this builder, see the
-   chapter :ref:`latex-options` for details.
-
-   Its name is ``latex``.
-
-.. class:: TextBuilder
-
-   This builder produces a text file for each reST file -- this is almost the
-   same as the reST source, but with much of the markup stripped for better
-   readability.
-
-   Its name is ``text``.
-
-   .. versionadded:: 0.4
-
-.. class:: SerializingHTMLBuilder
-
-   This builder uses a module that implements the Python serialization API
-   (`pickle`, `simplejson`, `phpserialize`, and others) to dump the generated
-   HTML documentation.  The pickle builder is a subclass of it.
-
-   A concreate subclass of this builder serializing to the `PHP serialization`_
-   format could look like this::
-
-        import phpserialize
-
-        class PHPSerializedBuilder(SerializingHTMLBuilder):
-            name = 'phpserialized'
-            implementation = phpserialize
-            out_suffix = '.file.phpdump'
-            globalcontext_filename = 'globalcontext.phpdump'
-            searchindex_filename = 'searchindex.phpdump'
-
-   .. _PHP serialization: http://pypi.python.org/pypi/phpserialize
-
-   .. attribute:: implementation
-    
-      A module that implements `dump()`, `load()`, `dumps()` and `loads()`
-      functions that conform to the functions with the same names from the
-      pickle module.  Known modules implementing this interface are
-      `simplejson` (or `json` in Python 2.6), `phpserialize`, `plistlib`,
-      and others.
-
-   .. attribute:: out_suffix
-
-      The suffix for all regular files.
-
-   .. attribute:: globalcontext_filename
-
-      The filename for the file that contains the "global context".  This
-      is a dict with some general configuration values such as the name
-      of the project.
-
-   .. attribute:: searchindex_filename
-
-      The filename for the search index Sphinx generates.
-
-
-   See :ref:`serialization-details` for details about the output format.
-
-   .. versionadded:: 0.5
-   
+.. module:: sphinx.builders.changes
 .. class:: ChangesBuilder
 
    This builder produces an HTML overview of all :dir:`versionadded`,
 
    Its name is ``changes``.
 
+.. module:: sphinx.builders.linkcheck
 .. class:: CheckExternalLinksBuilder
 
    This builder scans all documents for external links, tries to open them with

File doc/concepts.rst

 slashes.  All values, parameters and suchlike referring to "documents" expect
 such a document name.
 
+Examples for document names are ``index``, ``library/zipfile``, or
+``reference/datamodel/types``.  Note that there is no leading slash.
+
 
 The TOC tree
 ------------
      ``strings`` and so forth, and it knows that they are children of the shown
      document, the library index.  From this information it generates "next
      chapter", "previous chapter" and "parent chapter" links.
-     
+
    Document titles in the :dir:`toctree` will be automatically read from the
-   title of the referenced document. If that isn't what you want, you can give
-   the specify an explicit title and target using a similar syntax to reST
+   title of the referenced document. If that isn't what you want, you can
+   specify an explicit title and target using a similar syntax to reST
    hyperlinks (and Sphinx's :ref:`cross-referencing syntax <xref-syntax>`). This
    looks like::
-   
+
        .. toctree::
-          
+
           intro
           All about strings <strings>
           datatypes
-          
+
    The second line above will link to the ``strings`` document, but will use the
    title "All about strings" instead of the title of the ``strings`` document.
 
+   You can also add external links, by giving an HTTP URL instead of a document
+   name.
+
+   If you want to have section numbers even in HTML output, give the toctree a
+   ``numbered`` flag option.  For example::
+
+      .. toctree::
+         :numbered:
+
+         foo
+         bar
+
+   Numbering then starts at the heading of ``foo``.  Sub-toctrees are
+   automatically numbered (don't give the ``numbered`` flag to those).
+
    You can use "globbing" in toctree directives, by giving the ``glob`` flag
    option.  All entries are then matched against the list of available
    documents, and matches are inserted into the list alphabetically.  Example::
    This includes first all documents whose names start with ``intro``, then all
    documents in the ``recipe`` folder, then all remaining documents (except the
    one containing the directive, of course.) [#]_
-          
+
+   The special entry name ``self`` stands for the document containing the
+   toctree directive.  This is useful if you want to generate a "sitemap" from
+   the toctree.
+
+   You can also give a "hidden" option to the directive, like this::
+
+      .. toctree::
+         :hidden:
+
+         doc_1
+         doc_2
+
+   This will still notify Sphinx of the document hierarchy, but not insert links
+   into the document at the location of the directive -- this makes sense if you
+   intend to insert these links yourself, in a different style, or in the HTML
+   sidebar.
+
    In the end, all documents in the :term:`source directory` (or subdirectories)
    must occur in some ``toctree`` directive; Sphinx will emit a warning if it
    finds a file that is not included, because that means that this file will not
    .. versionchanged:: 0.3
       Added "globbing" option.
 
+   .. versionchanged:: 0.6
+      Added "numbered" and "hidden" options as well as external links and
+      support for "self" references.
+
 
 Special names
 -------------
 # -*- coding: utf-8 -*-
 #
-# Sphinx documentation build configuration file, created by
-# sphinx-quickstart.py on Sat Mar  8 21:47:50 2008.
-#
-# This file is execfile()d with the current directory set to its containing dir.
-#
-# The contents of this file are pickled, so don't put values in the namespace
-# that aren't pickleable (module imports are okay, they're removed automatically).
-#
-# All configuration values have a default value; values that are commented out
-# serve to show the default value.
+# Sphinx documentation build configuration file
 
 import sys, os, re
 
-# If your extensions are in another directory, add it here.
-#sys.path.append(os.path.dirname(__file__))
-
-# General configuration
-# ---------------------
-
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.addons.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest']
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.todo']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
 # General substitutions.
 project = 'Sphinx'
-copyright = '2008, Georg Brandl'
+copyright = '2007-2009, Georg Brandl'
 
 # The default replacements for |version| and |release|, also used in various
 # other places throughout the built documents.
-#
-# The short X.Y version.
 import sphinx
 version = sphinx.__released__
-# The full version, including alpha/beta/rc tags.
 release = version
 
-# There are two options for replacing |today|: either, you set today to some
-# non-false value, then it is used:
-#today = ''
-# Else, today_fmt is used as the format for a strftime call.
-#today_fmt = '%B %d, %Y'
-
-# List of documents that shouldn't be included in the build.
-#unused_docs = []
-
-# If true, '()' will be appended to :func: etc. cross-reference text.
-#add_function_parentheses = True
-
-# If true, the current module name will be prepended to all description
-# unit titles (such as .. function::).
-#add_module_names = True
-
+# Show author directives in the output.
 show_authors = True
 
-# The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'friendly'
+# The HTML template theme.
+html_theme = 'sphinxdoc'
 
-
-# Options for HTML output
-# -----------------------
-
-# The style sheet to use for HTML and HTML Help pages. A file of that name
-# must exist either in Sphinx' static/ path, or in one of the custom paths
-# given in html_static_path.
-html_style = 'sphinxdoc.css'
+# A list of ignored prefixes names for module index sorting.
+modindex_common_prefix = ['sphinx.']
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # using the given strftime format.
 html_last_updated_fmt = '%b %d, %Y'
 
-# If true, SmartyPants will be used to convert quotes and dashes to
-# typographically correct entities.
-#html_use_smartypants = True
-
 # Content template for the index page.
 html_index = 'index.html'
 
 # templates.
 html_additional_pages = {'index': 'index.html'}
 
-# If true, the reST sources are included in the HTML build as _sources/<name>.
-#html_copy_source = True
-
+# Generate an OpenSearch description with that URL as the base.
 html_use_opensearch = 'http://sphinx.pocoo.org'
 
 # Output file base name for HTML help builder.
 htmlhelp_basename = 'Sphinxdoc'
 
-
-# Options for LaTeX output
-# ------------------------
-
-# The paper size ('letter' or 'a4').
-#latex_paper_size = 'letter'
-
-# The font size ('10pt', '11pt' or '12pt').
-#latex_font_size = '10pt'
-
 # Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title, author, document class [howto/manual]).
+# (source start file, target name, title, author, documentclass [howto/manual]).
 latex_documents = [('contents', 'sphinx.tex', 'Sphinx Documentation',
                     'Georg Brandl', 'manual', 1)]
 
+# Add our logo to the LaTeX file.
 latex_logo = '_static/sphinx.png'
 
-#latex_use_parts = True
-
 # Additional stuff for the LaTeX preamble.
 latex_elements = {
     'fontpkg': '\\usepackage{palatino}'
 }
 
-# Documents to append as an appendix to all manuals.
-#latex_appendices = []
+# Put TODOs into the output.
+todo_include_todos = True
 
 
-# Extension interface
-# -------------------
+# -- Extension interface -------------------------------------------------------
 
 from sphinx import addnodes
 
 def setup(app):
     from sphinx.ext.autodoc import cut_lines
     app.connect('autodoc-process-docstring', cut_lines(4, what=['module']))
-    app.add_description_unit('directive', 'dir', 'pair: %s; directive', parse_directive)
+    app.add_description_unit('directive', 'dir', 'pair: %s; directive',
+                             parse_directive)
     app.add_description_unit('role', 'role', 'pair: %s; role', parse_role)
-    app.add_description_unit('confval', 'confval', 'pair: %s; configuration value')
+    app.add_description_unit('confval', 'confval',
+                             'pair: %s; configuration value')
     app.add_description_unit('event', 'event', 'pair: %s; event', parse_event)

File doc/config.rst

 
 * The term "fully-qualified name" refers to a string that names an importable
   Python object inside a module; for example, the FQN
-  ``"sphinx.builder.Builder"`` means the ``Builder`` class in the
-  ``sphinx.builder`` module.
+  ``"sphinx.builders.Builder"`` means the ``Builder`` class in the
+  ``sphinx.builders`` module.
 
 * Remember that document names use ``/`` as the path separator and don't contain
   the file name extension.
   delete them from the namespace with ``del`` if appropriate.  Modules are
   removed automatically, so you don't need to ``del`` your imports after use.
 
+* There is a special object named ``tags`` available in the config file.
+  It can be used to query and change the tags (see :ref:`tags`).  Use
+  ``tags.has('tag')`` to query, ``tags.add('tag')`` and ``tags.remove('tag')``
+  to change.
+
 
 General configuration
 ---------------------
 .. confval:: extensions
 
    A list of strings that are module names of Sphinx extensions.  These can be
-   extensions coming with Sphinx (named ``sphinx.addons.*``) or custom ones.
+   extensions coming with Sphinx (named ``sphinx.ext.*``) or custom ones.
 
    Note that you can extend :data:`sys.path` within the conf file if your
    extensions live in another directory -- but make sure you use absolute paths.
 
    .. versionadded:: 0.5
       Previously, Sphinx accepted only UTF-8 encoded sources.
-   
+
 .. confval:: master_doc
 
    The document name of the "master" document, that is, the document that
 .. confval:: templates_path
 
    A list of paths that contain extra templates (or templates that overwrite
-   builtin templates).  Relative paths are taken as relative to the
-   configuration directory.
+   builtin/theme-specific templates).  Relative paths are taken as relative to
+   the configuration directory.
 
 .. confval:: template_bridge
 
    A string with the fully-qualified name of a callable (or simply a class) that
    returns an instance of :class:`~sphinx.application.TemplateBridge`.  This
    instance is then used to render HTML documents, and possibly the output of
-   other builders (currently the changes builder).
+   other builders (currently the changes builder).  (Note that the template
+   bridge must be made theme-aware if HTML themes are to be used.)
+
+.. confval:: rst_epilog
+
+   .. index:: pair: global; substitutions
+
+   A string of reStructuredText that will be included at the end of every source
+   file that is read.  This is the right place to add substitutions that should
+   be available in every file.  An example::
+
+      rst_epilog = """
+      .. |psf| replace:: Python Software Foundation
+      """
+
+   .. versionadded:: 0.6
 
 .. confval:: default_role
 
+   .. index:: default; role
+
    The name of a reST role (builtin or Sphinx extension) to use as the default
    role, that is, for text marked up ```like this```.  This can be set to
    ``'obj'`` to make ```filter``` a cross-reference to the function "filter".
    .. versionadded:: 0.5
 
 
+.. confval:: modindex_common_prefix
+
+   A list of prefixes that are ignored for sorting the module index (e.g.,
+   if this is set to ``['foo.']``, then ``foo.bar`` is shown under ``B``, not
+   ``F``). This can be handy if you document a project that consists of a single
+   package.  Works only for the HTML builder currently.   Default is ``[]``.
+
+   .. versionadded:: 0.6
+
+
 Project information
 -------------------
-   
+
 .. confval:: project
 
    The documented project's name.
    * ``cs`` -- Czech
    * ``de`` -- German
    * ``en`` -- English
+   * ``es`` -- Spanish
+   * ``fi`` -- Finnish
    * ``fr`` -- French
+   * ``it`` -- Italian
+   * ``nl`` -- Dutch
    * ``pl`` -- Polish
+   * ``pt_BR`` -- Brazilian Portuguese
+   * ``sl`` -- Slovenian
+   * ``uk_UA`` -- Ukrainian
+   * ``zh_TW`` -- Traditional Chinese
 
 .. confval:: today
              today_fmt
    :ref:`code-examples` for more details.
 
    .. versionadded:: 0.5
-   
+
 .. confval:: pygments_style
 
    The style name to use for Pygments highlighting of source code.  Default is
    A boolean that decides whether :dir:`moduleauthor` and :dir:`sectionauthor`
    directives produce any output in the built files.
 
+.. confval:: trim_footnote_reference_space
+
+   Trim spaces before footnote references that are necessary for the reST parser
+   to recognize the footnote, but do not look too nice in the output.
+
+   .. versionadded:: 0.6
+
 
 .. _html-options:
 
 These options influence HTML as well as HTML Help output, and other builders
 that use Sphinx' HTMLWriter class.
 
+.. confval:: html_theme
+
+   The "theme" that the HTML output should use.  See the :doc:`section about
+   theming <theming>`.  The default is ``'default'``.
+
+   .. versionadded:: 0.6
+
+.. confval:: html_theme_options
+
+   A dictionary of options that influence the look and feel of the selected
+   theme.  These are theme-specific.  For the options understood by the builtin
+   themes, see :ref:`this section <builtin-themes>`.
+
+   .. versionadded:: 0.6
+
+.. confval:: html_theme_path
+
+   A list of paths that contain custom themes, either as subdirectories or as
+   zip files.  Relative paths are taken as relative to the configuration
+   directory.
+
+   .. versionadded:: 0.6
+
+.. confval:: html_style
+
+   The style sheet to use for HTML pages.  A file of that name must exist either
+   in Sphinx' :file:`static/` path, or in one of the custom paths given in
+   :confval:`html_static_path`.  Default is the stylesheet given by the selected
+   theme.  If you only want to add or override a few things compared to the
+   theme's stylesheet, use CSS ``@import`` to import the theme's stylesheet.
+
 .. confval:: html_title
 
    The "title" for HTML documentation generated with Sphinx' own templates.
 
    .. versionadded:: 0.4
 
-.. confval:: html_style
-
-   The style sheet to use for HTML pages.  A file of that name must exist either
-   in Sphinx' :file:`static/` path, or in one of the custom paths given in
-   :confval:`html_static_path`.  Default is ``'default.css'``.
-
 .. confval:: html_logo
 
    If given, this must be the name of an image file that is the logo of the
 
    A list of paths that contain custom static files (such as style sheets or
    script files).  Relative paths are taken as relative to the configuration
-   directory.  They are copied to the output directory after the builtin static
-   files, so a file named :file:`default.css` will overwrite the builtin
+   directory.  They are copied to the output directory after the theme's static
+   files, so a file named :file:`default.css` will overwrite the theme's
    :file:`default.css`.
 
    .. versionchanged:: 0.4
    If true, *SmartyPants* will be used to convert quotes and dashes to
    typographically correct entities.  Default: ``True``.
 
+.. 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``.
+
+   .. versionadded:: 0.6
+      Previously, this was always activated.
+
 .. confval:: html_sidebars
 
    Custom sidebar templates, must be a dictionary that maps document names to
    If true, the reST sources are included in the HTML build as
    :file:`_sources/{name}`.  The default is ``True``.
 
+   .. warning::
+
+      If this config value is set to ``False``, the JavaScript search function
+      will only display the titles of matching documents, and no excerpt from
+      the matching contents.
+
+.. confval:: html_show_sourcelink
+
+   If true (and :confval:`html_copy_source` is true as well), links to the
+   reST sources will be added to the sidebar.  The default is ``True``.
+
+   .. versionadded:: 0.6
+
 .. confval:: html_use_opensearch
 
    If nonempty, an `OpenSearch <http://opensearch.org>` description file will be
 
    .. versionadded:: 0.4
 
+.. confval:: html_link_suffix
+
+   Suffix for generated links to HTML files.  The default is whatever
+   :confval:`html_file_suffix` is set to; it can be set differently (e.g. to
+   support different web server setups).
+
+   .. versionadded:: 0.6
+
 .. confval:: html_translator_class
 
    A string with the fully-qualified name of a HTML Translator class, that is, a
-   subclass of Sphinx' :class:`~sphinx.htmlwriter.HTMLTranslator`, that is used
+   subclass of Sphinx' :class:`~sphinx.writers.html.HTMLTranslator`, that is used
    to translate document trees to HTML.  Default is ``None`` (use the builtin
    translator).
 
    avoid interpretation as escape sequences.
 
    * Keys that you may want to override include:
-     
+
      ``'papersize'``
         Paper size option of the document class (``'a4paper'`` or
         ``'letterpaper'``), default ``'letterpaper'``.
         Additional preamble content, default empty.
      ``'footer'```
         Additional footer content (before the indices), default empty.
-     
+
    * Keys that don't need be overridden unless in special cases are:
-     
+
      ``'inputenc'``
         "inputenc" package inclusion, default
         ``'\\usepackage[utf8]{inputenc}'``.
         "printindex" call, the last thing in the file, default
         ``'\\printindex'``.  Override if you want to generate the index
         differently or append some content after the index.
-     
+
    * Keys that are set by other options and therefore should not be overridden are:
-     
+
      ``'docclass'``
      ``'classoptions'``
      ``'title'``
      ``'makemodindex'``
      ``'shorthandoff'``
      ``'printmodindex'``
-   
+
+.. confval:: latex_additional_files
+
+   A list of file names, relative to the configuration directory, to copy to the
+   build directory when building LaTeX output.  This is useful to copy files
+   that Sphinx doesn't copy automatically, e.g. if they are referenced in custom
+   LaTeX added in ``latex_elements``.  Image files that are referenced in source
+   files (e.g. via ``.. image::``) are copied automatically.
+
+   You have to make sure yourself that the filenames don't collide with those of
+   any automatically copied files.
+
+   .. versionadded:: 0.6
+
 .. confval:: latex_preamble
 
    Additional LaTeX markup for the preamble.

File doc/contents.rst

    markup/index
    builders
    config
+   theming
    templating
    extensions
-   
+
+   faq
    glossary
    changes
    examples

File doc/ext/appapi.rst

 .. method:: Sphinx.add_builder(builder)
 
    Register a new builder.  *builder* must be a class that inherits from
-   :class:`~sphinx.builder.Builder`.
+   :class:`~sphinx.builders.Builder`.
 
-.. method:: Sphinx.add_config_value(name, default, rebuild_env)
+.. method:: Sphinx.add_config_value(name, default, rebuild)
 
    Register a configuration value.  This is necessary for Sphinx to recognize
    new values and set default values accordingly.  The *name* should be prefixed
    with the extension name, to avoid clashes.  The *default* value can be any
-   Python object.  The boolean value *rebuild_env* must be ``True`` if a change
-   in the setting only takes effect when a document is parsed -- this means that
-   the whole environment must be rebuilt.
+   Python object.  The string value *rebuild* must be one of those values:
+
+   * ``'env'`` if a change in the setting only takes effect when a document is
+     parsed -- this means that the whole environment must be rebuilt.
+   * ``'html'`` if a change in the setting needs a full rebuild of HTML
+     documents.
+   * ``''`` if a change in the setting will not need any special rebuild.
 
    .. versionchanged:: 0.4
       If the *default* value is a callable, it will be called with the config
       object as its argument in order to get the default value.  This can be
       used to implement config values whose default depends on other values.
 
+   .. versionchanged:: 0.6
+      Changed *rebuild* from a simple boolean (equivalent to ``''`` or
+      ``'env'``) to a string.  However, booleans are still accepted and
+      converted internally.
+
 .. method:: Sphinx.add_event(name)
 
    Register an event called *name*.
    :exc:`docutils.nodes.SkipNode`.  Example::
 
       class math(docutils.nodes.Element)
-   
+