Commits

SHIBUKAWA Yoshiki committed a5c533d Merge

import from latest sphinx code base

  • Participants
  • Parent commits e0b7a5a, cd7b0a8

Comments (0)

Files changed (225)

 3fcdbfa3afb181d3bec533be76ab1fcb446416bb 1.0.2
 fdf329d6066499c7d4190001b0510ad5b836c810 1.0.3
 d2c100cde633828d8656a5cdefbdbc167e2768a1 1.0.4
+878a1874a8e63f1b5a6b939ed86b6c120bf168c6 1.0.5
+48688502e78b09c03b877910b64368c5db9bb4ff 1.0.6
 * 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
 * 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
 
 * Added a Texinfo builder.
 
+* Incompatibility: 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.)
+
 * Added i18n support for content, a ``gettext`` builder and
   related utilities.
 
 
 * #460: Allow limiting the depth of section numbers for HTML.
 
+* #564: Add :confval:`autodoc_docstring_signature` which 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.
+
 * #138: Add an ``index`` role, to make inline index entries.
 
 * #443: Allow referencing external graphviz files.
 
+* Added the :mod:`sphinx.ext.mathjax` extension.
+
+* Added ``pyramid`` theme.
+
+* #98: Added a ``sphinx-apidoc`` script that autogenerates a
+  hierarchy of source files containing autodoc directives to
+  document modules and packages.
+
+* #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`.
+
+* #273: Add an API for adding full-text search support for languages
+  other than English.  Add support for Japanese.
+
 * #221: Add Swedish locale.
 
 * Added ``inline`` option to graphviz directives, and fixed the
 
 * #521: Added :confval:`linkcheck_ignore` config value.
 
+* #454: Add more index markup capabilities: marking see/seealso entries,
+  and main entries for a given key.
+
+* #516: Added new value of the :confval:`latex_show_urls` option to
+  show the URLs in footnotes.
+
 * #526: Added Iranian translation.
 
-
-Release 1.0.5 (in development)
+* #586: Implemented improved glossary markup which allows multiple terms per
+  definition.
+
+* #559: :confval:`html_add_permalinks` is now a string giving the
+  text to display in permalinks.
+
+* #553: Added :rst:dir:`testcleanup` blocks in the doctest extension.
+
+* #209: Added :confval:`text_newlines` and :confval:`text_sectionchars`
+  config values.
+
+* Added :confval:`man_show_urls` config value.
+
+* #259: HTML table rows now have even/odd CSS classes to enable
+  "Zebra styling".
+
+* #478: Added :rst:dir:`py:decorator` directive to describe decorators.
+
+* #367: Added automatic exclusion of hidden members in inheritance
+  diagrams, and an option to selectively enable it.
+
+* #306: Added :event:`env-get-outdated` event.
+
+* #590: Added ``caption`` option to graphviz directives.
+
+* #537: Added :confval:`nitpick_ignore`.
+
+* #437: autodoc now shows values of class data attributes.
+
+* autodoc now supports documenting the signatures of ``functools.partial``
+  objects.
+
+* Added :confval:`pngmath_add_tooltips`.
+
+* Section headings in :rst:dir:`only` directives are now correctly
+  handled.
+
+* C++ domain now supports array definitions.
+
+
+Release 1.0.7 (in development)
 ==============================
 
+* #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.
+
+
+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.
 * 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
 * Heapkeeper: http://heapkeeper.org/
 * 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.ee/
 * 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
 * NOC: http://trac.nocproject.org/trac/wiki/NocGuide
 * 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/
 * 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
 
 * C/C++ Development with Eclipse: http://book.dehlia.in/c-cpp-eclipse/ (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)
 * 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/
 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

File doc/Makefile

 
 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 "pdflatex finished; the PDF files are in _build/latex."
 
 gettext:
-	$(SPHINXBUILD) -b gettext $(ALLSPHINXOPTS) _build/locale
+	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) _build/locale
 	@echo
 	@echo "Build finished. The message catalogs are in _build/locale."
 

File 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

File doc/builders.rst

 
    .. versionadded:: 0.5
 
-.. module:: sphinx.builders.intl
+.. module:: sphinx.builders.gettext
 .. class:: MessageCatalogBuilder
 
    This builder produces gettext-style message catalos.  Each top-level file or
 exclude_patterns = ['_build']
 
 project = 'Sphinx'
-copyright = '2007-2010, Georg Brandl'
+copyright = '2007-2011, Georg Brandl'
 version = sphinx.__released__
 release = version
 show_authors = True
 latex_elements = {
     'fontpkg': '\\usepackage{palatino}',
 }
+latex_show_urls = 'footnote'
 
 autodoc_member_order = 'groupwise'
 todo_include_todos = True
 
 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])

File doc/config.rst

 
    .. 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
 -------------------
 These options influence HTML as well as HTML Help output, and other builders
 that use Sphinx' HTMLWriter class.
 
-.. XXX document html_context
-
 .. confval:: html_theme
 
    The "theme" that the HTML output should use.  See the :doc:`section about
 
    .. 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
 
    .. 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'``.
    a chapter, but can be confusing because it mixes entries of differnet
    depth in one list.  The default value is ``True``.
 
+
 .. _latex-options:
 
 Options for LaTeX output
 
 .. 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
 
    .. versionadded:: 1.0
 
+.. confval:: man_show_urls
+
+   If true, add URL addresses after links.  Default is ``False``.
+
+   .. versionadded:: 1.1
+
 
 .. _texinfo-options:
 
 
    .. versionadded:: 1.1
 
+.. confval:: linkcheck_timeout
+
+   A timeout value, in seconds, for the linkcheck builder.  **Only works in
+   Python 2.6 and higher.**  The default is to use Python's global socket
+   timeout.
+
+   .. versionadded:: 1.1
+
+.. confval:: linkcheck_workers
+
+   The number of worker threads to use when checking links.  Default is 5
+   threads.
+
+   .. versionadded:: 1.1
+
 
 .. rubric:: Footnotes
 

File doc/domains.rst

 
    .. versionadded:: 0.6
 
+.. rst:directive:: .. py:decorator:: name
+                   .. py:decorator:: name(signature)
+
+   Describes a decorator function.  The signature should *not* represent the
+   signature of the actual function, but the usage as a decorator.  For example,
+   given the functions
+
+   .. code-block:: python
+
+      def removename(func):
+          func.__name__ = ''
+          return func
+
+      def setnewname(name):
+          def decorator(func):
+              func.__name__ = name
+              return func
+          return decorator
+
+   the descriptions should look like this::
+
+      .. py:decorator:: removename
+
+         Remove name of the decorated function.
+
+      .. py:decorator:: setnewname(name)
+
+         Set name of the decorated function to *name*.
+
+   There is no ``py:deco`` role to link to a decorator that is marked up with
+   this directive; rather, use the :rst:role:`py:func` role.
+
+.. rst:directive:: .. py:decoratormethod:: name
+                   .. py:decoratormethod:: name(signature)
+
+   Same as :rst:dir:`py:decorator`, but for decorators that are methods.
+
+   Refer to a decorator method using the :rst:role:`py:meth` role.
+
 
 .. _signatures:
 
       :type limit: integer or None
       :rtype: list of strings
 
-It is also possible to combine parameter type and description, if the type is a
-single word, like this::
-
-   :param integer limit: maximum number of stack frames to show
-
 This will render like this:
 
    .. py:function:: format_exception(etype, value, tb[, limit=None])
       :type limit: integer or None
       :rtype: list of strings
 
+It is also possible to combine parameter type and description, if the type is a
+single word, like this::
+
+   :param integer limit: maximum number of stack frames to show
+
+
+.. _python-roles:
 
 Cross-referencing Python objects
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
       .. c:var:: PyObject* PyClass_Type
 
 
+.. _c-roles:
+
 Cross-referencing C constructs
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 
    Select the current C++ namespace for the following objects.
 
+
+.. _cpp-roles:
+
 These roles link to the given object types:
 
 .. rst:role:: cpp:class
 
    Describes the attribute *name* of *object*.
 
+.. _js-roles:
+
 These roles are provided to refer to the described objects:
 
 .. rst:role:: js:func
 
          Foo description.
 
+.. _rst-roles:
+
 These roles are provided to refer to the described objects:
 
 .. rst:role:: rst:dir

File doc/ext/appapi.rst

 
    .. versionadded:: 0.6
 
-.. method:: Sphinx.add_object_type(directivename, rolename, indextemplate='', parse_node=None, ref_nodeclass=None, objname='')
+.. method:: Sphinx.add_object_type(directivename, rolename, indextemplate='', parse_node=None, \
+                                   ref_nodeclass=None, objname='', doc_field_types=[])
 
    This method is a very convenient way to add a new :term:`object` type that
    can be cross-referenced.  It will do this:
 
    .. versionadded:: 0.6
 
+.. method:: Sphinx.add_search_language(cls)
+
+   Add *cls*, which must be a subclass of :class:`sphinx.search.SearchLanguage`,
+   as a support language for building the HTML full-text search index.  The
+   class must have a *lang* attribute that indicates the language it should be
+   used for.  See :confval:`html_search_language`.
+
+   .. versionadded:: 1.1
+
 .. method:: Sphinx.connect(event, callback)
 
    Register *callback* to be called when *event* is emitted.  For details on
    Emitted when the builder object has been created.  It is available as
    ``app.builder``.
 
+.. event:: env-get-outdated (app, env, added, changed, removed)
+
+   Emitted when the environment determines which source files have changed and
+   should be re-read.  *added*, *changed* and *removed* are sets of docnames
+   that the environment has determined.  You can return a list of docnames to
+   re-read in addition to these.
+
+   .. versionadded:: 1.1
+
 .. event:: env-purge-doc (app, env, docname)
 
    Emitted when all traces of a source file should be cleaned from the

File doc/ext/autodoc.rst

         .. autoclass:: Noodle
            :members: eat, slurp
 
-   * If you want to make the ``members`` option the default, see
-     :confval:`autodoc_default_flags`.
+   * If you want to make the ``members`` option (or other flag options described
+     below) the default, see :confval:`autodoc_default_flags`.
 
    * Members without docstrings will be left out, unless you give the
      ``undoc-members`` flag option::
            :members:
            :undoc-members:
 
+   * "Private" members (that is, those named like ``_private`` or ``__private``)
+     will be included if the ``private-members`` flag option is given.
+
+     .. versionadded:: 1.1
+
+   * Python "special" members (that is, those named like ``__special__``) will
+     be included if the ``special-members`` flag option is given::
+
+        .. autoclass:: my.Class
+           :members:
+           :private-members:
+           :special-members:
+
+     would document both "private" and "special" members of the class.
+
+     .. versionadded:: 1.1
+
    * For classes and exceptions, members inherited from base classes will be
-     left out, unless you give the ``inherited-members`` flag option, in
-     addition to ``members``::
+     left out when documenting all members, unless you give the
+     ``inherited-members`` flag option, in addition to ``members``::
 
         .. autoclass:: Noodle
            :members:
 
      .. versionadded:: 0.5
 
-   * :rst:dir:`automodule` and :rst:dir:`autoclass` also has an ``member-order`` option
-     that can be used to override the global value of
+   * :rst:dir:`automodule` and :rst:dir:`autoclass` also has an ``member-order``
+     option that can be used to override the global value of
      :confval:`autodoc_member_order` for one directive.
 
      .. versionadded:: 0.6
 
 
 .. rst:directive:: autofunction
-               autodata
-               automethod
-               autoattribute
+                   autodata
+                   automethod
+                   autoattribute
 
    These work exactly like :rst:dir:`autoclass` etc., but do not offer the options
    used for automatic member documentation.
 
           baz = 2
           """Docstring for class attribute Foo.baz."""
-          
+
           def __init__(self):
               #: Doc comment for instance attribute qux.
               self.qux = 3
-              
+
               self.spam = 4
               """Docstring for instance attribute spam."""
 
 
    This value is a list of autodoc directive flags that should be automatically
    applied to all autodoc directives.  The supported flags are ``'members'``,
-   ``'undoc-members'``, ``'inherited-members'`` and ``'show-inheritance'``.
+   ``'undoc-members'``, ``'private-members'``, ``'special-members'``,
+   ``'inherited-members'`` and ``'show-inheritance'``.
 
    If you set one of these flags in this config value, you can use a negated
    form, :samp:`'no-{flag}'`, in an autodoc directive, to disable it once.
 
    .. versionadded:: 1.0
 
+.. confval:: autodoc_docstring_signature
+
+   Functions imported from C modules cannot be introspected, and therefore the
+   signature for such functions cannot be automatically determined.  However, it
+   is an often-used convention to put the signature into the first line of the
+   function's docstring.
+
+   If this boolean value is set to ``True`` (which is the default), autodoc will
+   look at the first line of the docstring for functions and methods, and if it
+   looks like a signature, use the line as the signature and remove it from the
+   docstring content.
+
+   .. versionadded:: 1.1
+
 
 Docstring preprocessing
 -----------------------

File doc/ext/coverage.rst

 
 .. todo:: Write this section.
 
+
 Several new configuration values can be used to specify what the builder
 should check:
 
 .. confval:: coverage_c_regexes
 
 .. confval:: coverage_ignore_c_items
+
+.. confval:: coverage_write_headline
+
+   Set to ``False`` to not write headlines.
+
+   .. versionadded:: 1.1
+
+.. confval:: coverage_skip_undoc_in_source
+
+   Skip objects that are not documented in the source with a docstring.
+   ``False`` by default.
+
+   .. versionadded:: 1.1

File doc/ext/doctest.rst

    but executed before the doctests of the group(s) it belongs to.
 
 
+.. rst:directive:: .. testcleanup:: [group]
+
+   A cleanup code block.  This code is not shown in the output for other
+   builders, but executed after the doctests of the group(s) it belongs to.
+
+   .. versionadded:: 1.1
+
+
 .. rst:directive:: .. doctest:: [group]
 
    A doctest-style code block.  You can use standard :mod:`doctest` flags for
 
    .. versionadded:: 0.6
 
+.. confval:: doctest_global_cleanup
+
+   Python code that is treated like it were put in a ``testcleanup`` directive
+   for *every* file that is tested, and for every group.  You can use this to
+   e.g. remove any temporary files that the tests leave behind.
+
+   .. versionadded:: 1.1
+
 .. confval:: doctest_test_doctest_blocks
 
    If this is a nonempty string (the default is ``'default'``), standard reST

File doc/ext/graphviz.rst

    the graphviz code.
 
 .. versionadded:: 1.1
-   All three directives support an ``inline`` flag that controls
-   paragraph breaks in the output.  When set, the graph is inserted
-   into the current paragraph.  If the flag is not given, paragraph
-   breaks are introduced before and after the image (the default).
+   All three directives support an ``inline`` flag that controls paragraph
+   breaks in the output.  When set, the graph is inserted into the current
+   paragraph.  If the flag is not given, paragraph breaks are introduced before
+   and after the image (the default).
+
+.. versionadded:: 1.1
+   All three directives support a ``caption`` option that can be used to give a
+   caption to the diagram.  Naturally, diagrams marked as "inline" cannot have a
+   caption.
 
 There are also these new config values:
 

File doc/ext/inheritance.rst

    ``lib.``, you can give ``:parts: 1`` to remove that prefix from the displayed
    node names.)
 
+   It also supports a ``private-bases`` flag option; if given, private base
+   classes (those whose name starts with ``_``) will be included.
+
+   .. versionchanged:: 1.1
+      Added ``private-bases`` option; previously, all bases were always
+      included.
+
 
 New config values are:
 

File doc/ext/math.rst

    Unfortunately, this only works when the `preview-latex package`_ is
    installed.  Therefore, the default for this option is ``False``.
 
+.. confval:: pngmath_add_tooltips
+
+   Default: true.  If false, do not add the LaTeX code as an "alt" attribute for
+   math images.
+
+   .. versionadded:: 1.1
+
+
+:mod:`sphinx.ext.mathjax` -- Render math via JavaScript
+-------------------------------------------------------
+
+.. module:: sphinx.ext.mathjax
+   :synopsis: Render math using JavaScript via MathJax.
+
+.. versionadded:: 1.1
+
+This extension puts math as-is into the HTML files.  The JavaScript package
+MathJax_ is then loaded and transforms the LaTeX markup to readable math live in
+the browser.
+
+Because MathJax (and the necessary fonts) is very large, it is not included in
+Sphinx.  You must install it yourself, and give Sphinx its path in this config
+value:
+
+.. confval:: mathjax_path
+
+   The path to the JavaScript file to include in the HTML files in order to load
+   JSMath.  There is no default.
+
+   The path can be absolute or relative; if it is relative, it is relative to
+   the ``_static`` directory of the built docs.
+
+   For example, if you put JSMath into the static path of the Sphinx docs, this
+   value would be ``MathJax/MathJax.js``.  If you host more than one Sphinx
+   documentation set on one server, it is advisable to install MathJax in a
+   shared location.
+
+   You can also give a full ``http://`` URL.  Kevin Dunn maintains a MathJax
+   installation on a public server, which he offers for use by development and
+   production servers::
+
+      mathjax_path = 'http://mathjax.connectmv.com/MathJax.js'
+
 
 :mod:`sphinx.ext.jsmath` -- Render math via JavaScript
 ------------------------------------------------------
 
 .. module:: sphinx.ext.jsmath
-   :synopsis: Render math via JavaScript.
+   :synopsis: Render math using JavaScript via JSMath.
 
-This extension puts math as-is into the HTML files.  The JavaScript package
-jsMath_ is then loaded and transforms the LaTeX markup to readable math live in
-the browser.
-
-Because jsMath (and the necessary fonts) is very large, it is not included in
-Sphinx.  You must install it yourself, and give Sphinx its path in this config
-value:
+This extension works just as the MathJax extension does, but uses the older
+package jsMath_.  It provides this config value:
 
 .. confval:: jsmath_path
 
 
 
 .. _dvipng: http://savannah.nongnu.org/projects/dvipng/
+.. _MathJax: http://www.mathjax.org/
 .. _jsMath: http://www.math.union.edu/~dpvc/jsmath/
 .. _preview-latex package: http://www.gnu.org/software/auctex/preview-latex.html
 .. _AmSMath LaTeX package: http://www.ams.org/tex/amslatex.html
    Sphinx documentation to the PyPI package documentation area at
    http://packages.python.org/.
 
-github pages
-   You can use `Michael Jones' sphinx-to-github tool
-   <http://github.com/michaeljones/sphinx-to-github/tree/master>`_ to prepare
-   Sphinx HTML output.
+GitHub Pages
+   Directories starting with underscores are ignored by default which breaks
+   static files in Sphinx.  GitHub's preprocessor can be `disabled
+   <https://github.com/blog/572-bypassing-jekyll-on-github-pages>`_ to support
+   Sphinx HTML output properly.
+
+MediaWiki
+   See http://bitbucket.org/kevindunn/sphinx-wiki, a project by Kevin Dunn.
 
 Google Analytics
    You can use a custom ``layout.html`` template, like this:
          (widen) (goto-char (point-min))
          (when (re-search-forward
                 "^Generated by \\(Sphinx\\|Docutils\\)"
-                (save-excursion (search-forward "" nil t)) t)
+                (save-excursion (search-forward "^_" nil t)) t)
            (set (make-local-variable 'Info-hide-note-references)
                 'hide)))))
 

File doc/glossary.rst

       A reStructuredText markup element that allows marking a block of content
       with special meaning.  Directives are supplied not only by docutils, but
       Sphinx and custom extensions can add their own.  The basic directive
-      syntax looks like this::
+      syntax looks like this:
+
+      .. sourcecode:: rst
 
          .. directivename:: argument ...
             :option: value

File doc/intl.rst

 .. figure:: translation.png
    :width: 100%
 
-   Workflow visualization of translations in Sphinx. [1]_
+   Workflow visualization of translations in Sphinx.  (The stick-figure is taken
+   from an `XKCD comic <http://xkcd.com/779/>`_.)
 
-**gettext** [2]_ is an established standard for internationalization and
+**gettext** [1]_ is an established standard for internationalization and
 localization.  It naïvely maps messages in a program to a translated string.
 Sphinx uses these facilities to translate whole documents.
 
 way to do that.
 
 After Sphinx successfully ran the
-:class:`~sphinx.builders.intl.MessageCatalogBuilder` you will find a collection
+:class:`~sphinx.builders.gettext.MessageCatalogBuilder` you will find a collection
 of ``.pot`` files in your output directory.  These are **catalog templates**
 and contain messages in your original language *only*.
 
 
 An example: you have a document ``usage.rst`` in your Sphinx project.  The
 gettext builder will put its messages into ``usage.pot``.  Image you have
-Spanish translations [3]_ on your hands in ``usage.po`` --- for your builds to
+Spanish translations [2]_ on your hands in ``usage.po`` --- for your builds to
 be translated you need to follow these instructions:
 
 * Compile your message catalog to a locale directory, say ``translated``, so it
 
 .. rubric:: Footnotes
 
-.. [1] The stick-figure is taken from an `XKCD comic <http://xkcd.com/779/>`_.
-.. [2] See the `GNU gettext utilites
+.. [1] See the `GNU gettext utilites
        <http://www.gnu.org/software/gettext/manual/gettext.html#Introduction>`_
        for details on that software suite.
-.. [3] Because nobody expects the Spanish Inquisition!
+.. [2] Because nobody expects the Spanish Inquisition!

File doc/markup/inline.rst

   tool-tip on mouse-hover) will always be the full target name.
 
 
+Cross-referencing objects
+-------------------------
+
+These roles are described with their respective domains:
+
+* :ref:`Python <python-roles>`
+* :ref:`C <c-roles>`
+* :ref:`C++ <cpp-roles>`
+* :ref:`JavaScript <js-roles>`
+* :ref:`ReST <rst-roles>`
+
+
 .. _ref-role:
 
 Cross-referencing arbitrary locations

File doc/markup/misc.rst

 
    :fieldname: Field content
 
-A field list at the very top of a file is parsed by docutils as the "docinfo",
+A field list near the top of a file is parsed by docutils as the "docinfo"
 which is normally used to record the author, date of publication and other
-metadata.  *In Sphinx*, the docinfo is used as metadata, too, but not displayed
-in the output.
+metadata.  *In Sphinx*, a field list preceding any other markup is moved from
+the docinfo to the Sphinx environment as document metadata and is not displayed
+in the output; a field list appearing after the document title will be part of
+the docinfo as normal and will be displayed in the output.
 
 At the moment, these metadata fields are recognized:
 
       Likewise, ``triple: module; search; path`` is a shortcut that creates
       three index entries, which are ``module; search path``, ``search; path,
       module`` and ``path; module search``.
+   see
+      ``see: entry; other`` creates an index entry that refers from ``entry`` to
+      ``other``.
+   seealso
+      Like ``see``, but inserts "see also" instead of "see".
    module, keyword, operator, object, exception, statement, builtin
       These all create two index entries.  For example, ``module: hashlib``
       creates the entries ``module; hashlib`` and ``hashlib; module``.  (These
       are Python-specific and therefore deprecated.)
 
+   You can mark up "main" index entries by prefixing them with an exclamation
+   mark.  The references to "main" entries are emphasized in the generated
+   index.  For example, if two pages contain ::
+
+      .. index:: Python
+
+   and one page contains ::
+
+      .. index:: ! Python
+
+   then the backlink to the latter page is emphasized among the three backlinks.
+
    For index directives containing only "single" entries, there is a shorthand
    notation::
 
 
    This creates four index entries.
 
+   .. versionchanged:: 1.1
+      Added ``see`` and ``seealso`` types, as well as marking main entries.
+
 .. rst:role:: index
 
    While the :rst:dir:`index` directive is a block-level markup and links to the
 
    Undefined tags are false, defined tags (via the ``-t`` command-line option or
    within :file:`conf.py`) are true.  Boolean expressions, also using
-   parentheses (like ``html and (latex or draft)`` are supported.
+   parentheses (like ``html and (latex or draft)``) are supported.
 
    The format of the current builder (``html``, ``latex`` or ``text``) is always
    set as a tag.
 
 .. warning::
 
-   Tables that contain literal blocks cannot be set with ``tabulary``.  They are
-   therefore set with the standard LaTeX ``tabular`` environment.  Also, the
-   verbatim environment used for literal blocks only works in ``p{width}``
-   columns, which means that by default, Sphinx generates such column specs for
-   such tables.  Use the :rst:dir:`tabularcolumns` directive to get finer control
-   over such tables.
+   Tables that contain list-like elements such as object descriptions,
+   blockquotes or any kind of lists cannot be set out of the box with
+   ``tabulary``.  They are therefore set with the standard LaTeX ``tabular``
+   environment if you don't give a ``tabularcolumns`` directive.  If you do, the
+   table will be set with ``tabulary``, but you must use the ``p{width}``
+   construct for the columns that contain these elements.
+
+   Literal blocks do not work with ``tabulary`` at all, so tables containing a
+   literal block are always set with ``tabular``.  Also, the verbatim
+   environment used for literal blocks only works in ``p{width}`` columns, which
+   means that by default, Sphinx generates such column specs for such tables.
+   Use the :rst:dir:`tabularcolumns` directive to get finer control over such
+   tables.

File doc/markup/para.rst

 
 .. rst:directive:: .. glossary::
 
-   This directive must contain a reST definition list with terms and
-   definitions.  The definitions will then be referencable with the :rst:role:`term`
-   role.  Example::
+   This directive must contain a reST definition-list-like markup with terms and
+   definitions.  The definitions will then be referencable with the
+   :rst:role:`term` role.  Example::
 
       .. glossary::
 
             The directory which, including its subdirectories, contains all
             source files for one Sphinx project.
 
+   In contrast to regular definition lists, *multiple* terms per entry are
+   allowed, and inline markup is allowed in terms.  You can link to all of the
+   terms.  For example::
+
+      .. glossary::
+
+         term 1
+         term 2
+            Definition of both terms.
+
+   (When the glossary is sorted, the first term determines the sort order.)
+
    .. versionadded:: 0.6
       You can now give the glossary directive a ``:sorted:`` flag that will
       automatically sort the entries alphabetically.
 
+   .. versionchanged:: 1.1
+      Now supports multiple terms and inline markup in terms.
+
 
 Grammar production displays
 ---------------------------

File doc/themes/fullsize/pyramid.png

Added
New image

File doc/themes/pyramid.png

Added
New image

File doc/theming.rst

 |                    |                    |
 | *traditional*      | *nature*           |
 +--------------------+--------------------+
-| |haiku|            |                    |
+| |haiku|            | |pyramid|          |
 |                    |                    |
-| *haiku*            |                    |
+| *haiku*            | *pyramid*          |
 +--------------------+--------------------+
 
 .. |default|     image:: themes/default.png
 .. |traditional| image:: themes/traditional.png
 .. |nature|      image:: themes/nature.png
 .. |haiku|       image:: themes/haiku.png
+.. |pyramid|     image:: themes/pyramid.png
 
 Sphinx comes with a selection of themes to choose from.
 
   on the right side.  There are currently no options beyond *nosidebar*.
 
 * **scrolls** -- A more lightweight theme, based on `the Jinja documentation
-  <http://jinja.pocoo.org/2/documentation/>`_.  The following color options are
-  available:
+  <http://jinja.pocoo.org/>`_.  The following color options are available:
 
   - **headerbordercolor**
   - **subheadlinecolor**
 * **nature** -- A greenish theme.  There are currently no options beyond
   *nosidebar*.
 
+* **pyramid** -- A theme from the Pyramid web framework project, designed by
+  Blaise Laflamme.  THere are currently no options beyond *nosidebar*.
+
 * **haiku** -- A theme without sidebar inspired by the `Haiku OS user guide
   <http://www.haiku-os.org/docs/userguide/en/contents.html>`_.  The following
   options are supported:
 * A :file:`theme.conf` file, see below.
 * HTML templates, if needed.
 * A ``static/`` directory containing any static files that will be copied to the
-  output statid directory on build.  These can be images, styles, script files.
+  output static directory on build.  These can be images, styles, script files.
 
 The :file:`theme.conf` file is in INI format [1]_ (readable by the standard
 Python :mod:`ConfigParser` module) and has the following structure:

File doc/web/quickstart.rst

                                  username=username, proposal=proposal,
                                  displayed=False)
 
-You can then create two new views to handle the moderation of comments.  The
-first will be called when a moderator decides a comment should be accepted and
+You can then create a new view to handle the moderation of comments.  It
+will be called when a moderator decides a comment should be accepted and
 displayed::
 
    @app.route('/docs/accept_comment', methods=['POST'])
        support.accept_comment(comment_id, moderator=moderator)
        return 'OK'
 
-The next is very similar, but used when rejecting a comment::
-
-   @app.route('/docs/reject_comment', methods=['POST'])
-   def reject_comment():
-       moderator = g.user.moderator if g.user else False
-       comment_id = request.form.get('id')
-       support.reject_comment(comment_id, moderator=moderator)
-       return 'OK'
+Rejecting comments happens via comment deletion.
 
 To perform a custom action (such as emailing a moderator) when a new comment is
 added but not displayed, you can pass callable to the :class:`~.WebSupport`

File doc/web/storagebackends.rst

 .. automethod:: StorageBackend.update_username
 
 .. automethod:: StorageBackend.accept_comment
-
-.. automethod:: StorageBackend.reject_comment
         'console_scripts': [
             'sphinx-build = sphinx:main',
             'sphinx-quickstart = sphinx.quickstart:main',
+            'sphinx-apidoc = sphinx.apidoc:main',
             'sphinx-autogen = sphinx.ext.autosummary.generate:main',
         ],
         'distutils.commands': [

File sphinx-apidoc.py

+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+"""
+    Sphinx - Python documentation toolchain
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+    :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS.
+    :license: BSD, see LICENSE for details.
+"""
+
+import sys
+
+if __name__ == '__main__':
+    from sphinx.apidoc import main
+    sys.exit(main(sys.argv))

File sphinx-autogen.py

     Sphinx - Python documentation toolchain
     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-    :copyright: 2007-2010 by Georg Brandl.
-    :license: BSD.
+    :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS.
+    :license: BSD, see LICENSE for details.
 """
 
 import sys

File sphinx-build.py

     Sphinx - Python documentation toolchain
     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-    :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
+    :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS.
     :license: BSD, see LICENSE for details.
 """
 

File sphinx-quickstart.py

     Sphinx - Python documentation toolchain
     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-    :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
+    :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS.
     :license: BSD, see LICENSE for details.
 """
 

File sphinx/__init__.py

 
     The Sphinx documentation toolchain.
 
-    :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
+    :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS.
     :license: BSD, see LICENSE for details.
 """
 

File sphinx/addnodes.py

 
     Additional docutils nodes.
 
-    :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
+    :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS.
     :license: BSD, see LICENSE for details.
 """
 
 class abbreviation(nodes.Inline, nodes.TextElement):
     """Node for abbreviations with explanations."""
 
+class termsep(nodes.Structural, nodes.Element):
+    """Separates two terms within a <term> node."""
+
 
 # make the new nodes known to docutils; needed because the HTML writer will
 # choke at some point if these are not added

File sphinx/apidoc.py

+# -*- coding: utf-8 -*-
+"""
+    sphinx.apidoc
+    ~~~~~~~~~~~~~
+
+    Parses a directory tree looking for Python modules and packages and creates
+    ReST files appropriately to create code documentation with Sphinx.  It also
+    creates a modules index (named modules.<suffix>).
+
+    :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS.
+    :license: BSD, see LICENSE for details.
+"""
+import os
+import sys
+import optparse
+from os import path
+
+# automodule options
+OPTIONS = [
+    'members',
+    'undoc-members',
+    # 'inherited-members', # disabled because there's a bug in sphinx
+    'show-inheritance',
+]
+
+INITPY = '__init__.py'
+
+def makename(package, module):
+    """Join package and module with a dot."""
+    # Both package and module can be None/empty.
+    if package:
+        name = package
+        if module:
+            name += '.' + module
+    else:
+        name = module
+    return name
+
+def write_file(name, text, opts):
+    """Write the output file for module/package <name>."""
+    fname = path.join(opts.destdir, "%s.%s" % (name, opts.suffix))
+    if opts.dryrun:
+        print 'Would create file %s.' % fname
+        return
+    if not opts.force and path.isfile(fname):
+        print 'File %s already exists, skipping.' % fname
+    else:
+        print 'Creating file %s.' % fname
+        f = open(fname, 'w')
+        try:
+            f.write(text)
+        finally:
+            f.close()
+
+def format_heading(level, text):
+    """Create a heading of <level> [1, 2 or 3 supported]."""
+    underlining = ['=', '-', '~', ][level-1] * len(text)
+    return '%s\n%s\n\n' % (text, underlining)
+
+def format_directive(module, package=None):
+    """Create the automodule directive and add the options."""
+    directive = '.. automodule:: %s\n' % makename(package, module)
+    for option in OPTIONS:
+        directive += '    :%s:\n' % option
+    return directive
+
+def create_module_file(package, module, opts):
+    """Build the text of the file and write the file."""
+    text = format_heading(1, '%s Module' % module)
+    #text += format_heading(2, ':mod:`%s` Module' % module)
+    text += format_directive(module, package)
+    write_file(makename(package, module), text, opts)
+
+def create_package_file(root, master_package, subroot, py_files, opts, subs):
+    """Build the text of the file and write the file."""
+    package = path.split(root)[-1]
+    text = format_heading(1, '%s Package' % package)
+    # add each module in the package
+    for py_file in py_files:
+        if shall_skip(path.join(root, py_file)):
+            continue
+        is_package = py_file == INITPY
+        py_file = path.splitext(py_file)[0]
+        py_path = makename(subroot, py_file)
+        if is_package:
+            heading = ':mod:`%s` Package' % package
+        else:
+            heading = ':mod:`%s` Module' % py_file
+        text += format_heading(2, heading)
+        text += format_directive(is_package and subroot or py_path,
+                                 master_package)
+        text += '\n'
+
+    # build a list of directories that are packages (they contain an INITPY file)
+    subs = [sub for sub in subs if path.isfile(path.join(root, sub, INITPY))]
+    # if there are some package directories, add a TOC for theses subpackages
+    if subs:
+        text += format_heading(2, 'Subpackages')
+        text += '.. toctree::\n\n'
+        for sub in subs:
+            text += '    %s.%s\n' % (makename(master_package, subroot), sub)
+        text += '\n'
+
+    write_file(makename(master_package, subroot), text, opts)
+
+def create_modules_toc_file(master_package, modules, opts, name='modules'):
+    """
+    Create the module's index.
+    """
+    text = format_heading(1, '%s Modules' % opts.header)
+    text += '.. toctree::\n'
+    text += '   :maxdepth: %s\n\n' % opts.maxdepth
+
+    modules.sort()
+    prev_module = ''
+    for module in modules:
+        # look if the module is a subpackage and, if yes, ignore it
+        if module.startswith(prev_module + '.'):
+            continue
+        prev_module = module
+        text += '   %s\n' % module
+
+    write_file(name, text, opts)
+
+def shall_skip(module):
+    """
+    Check if we want to skip this module.
+    """
+    # skip it, if there is nothing (or just \n or \r\n) in the file
+    return path.getsize(module) < 3
+
+def recurse_tree(rootpath, excludes, opts):
+    """
+    Look for every file in the directory tree and create the corresponding
+    ReST files.
+    """
+    # check if the base directory is a package and get is name
+    if INITPY in os.listdir(rootpath):
+        package_name = path.abspath(rootpath).split(path.sep)[-1]
+    else:
+        package_name = None
+
+    toc = []
+    tree = os.walk(rootpath, False)
+    for root, subs, files in tree:
+        # keep only the Python script files
+        py_files =  sorted([f for f in files if path.splitext(f)[1] == '.py'])
+        if INITPY in py_files:
+            py_files.remove(INITPY)
+            py_files.insert(0, INITPY)
+        # remove hidden ('.') and private ('_') directories
+        subs = sorted([sub for sub in subs if sub[0] not in ['.', '_']])
+        # check if there are valid files to process
+        # TODO: could add check for windows hidden files
+        if "/." in root or "/_" in root \
+               or not py_files \
+               or is_excluded(root, excludes):
+            continue
+        if INITPY in py_files:
+            # we are in package ...
+            if (# ... with subpackage(s)
+                subs
+                or
+                # ... with some module(s)
+                len(py_files) > 1
+                or
+                # ... with a not-to-be-skipped INITPY file
+                not shall_skip(path.join(root, INITPY))
+               ):
+                subroot = root[len(rootpath):].lstrip(path.sep).\
+                          replace(path.sep, '.')
+                create_package_file(root, package_name, subroot,
+                                    py_files, opts, subs)
+                toc.append(makename(package_name, subroot))
+        elif root == rootpath:
+            # if we are at the root level, we don't require it to be a package
+            for py_file in py_files:
+                if not shall_skip(path.join(rootpath, py_file)):
+                    module = path.splitext(py_file)[0]
+                    create_module_file(package_name, module, opts)
+                    toc.append(makename(package_name, module))
+
+    # create the module's index
+    if not opts.notoc:
+        create_modules_toc_file(package_name, toc, opts)
+
+def normalize_excludes(rootpath, excludes):
+    """
+    Normalize the excluded directory list:
+    * must be either an absolute path or start with rootpath,
+    * otherwise it is joined with rootpath
+    * with trailing slash
+    """
+    sep = path.sep
+    f_excludes = []
+    for exclude in excludes:
+        if not path.isabs(exclude) and not exclude.startswith(rootpath):
+            exclude = path.join(rootpath, exclude)
+        if not exclude.endswith(sep):
+            exclude += sep
+        f_excludes.append(exclude)
+    return f_excludes
+
+def is_excluded(root, excludes):
+    """
+    Check if the directory is in the exclude list.
+
+    Note: by having trailing slashes, we avoid common prefix issues, like
+          e.g. an exlude "foo" also accidentally excluding "foobar".
+    """
+    sep = path.sep
+    if not root.endswith(sep):
+        root += sep
+    for exclude in excludes:
+        if root.startswith(exclude):
+            return True
+    return False
+
+def main(argv):
+    """
+    Parse and check the command line arguments.
+    """
+    parser = optparse.OptionParser(
+        usage="""\
+usage: %prog [options] -o <output_path> <module_path> [exclude_paths, ...]
+
+Look recursively in <module_path> for Python modules and packages and create
+a reST file with automodule directives per package in the <output_path>.
+
+Note: By default this script will not overwrite already created files.""")
+
+    parser.add_option('-o', '--output-dir', action='store', dest='destdir',
+                      help='Directory to place all output', default='')
+    parser.add_option('-d', '--maxdepth', action='store', dest='maxdepth',
+                      help='Maximum depth of submodules to show in the TOC '
+                      '(default: 4)', type='int', default=4)
+    parser.add_option('-f', '--force', action='store_true', dest='force',
+                      help='Overwrite all the files')
+    parser.add_option('-n', '--dry-run', action='store_true', dest='dryrun',
+                      help='Run the script without creating the files')
+    parser.add_option('-T', '--no-toc', action='store_true', dest='notoc',
+                      help='Don\'t create the table of contents file')
+    parser.add_option('-H', '--doc-header', action='store', dest='header',
+                      help='Documentation Header (default: Project)',
+                      default='Project')
+    parser.add_option('-s', '--suffix', action='store', dest='suffix',
+                      help='file suffix (default: rst)', default='rst')
+
+    (opts, args) = parser.parse_args(argv[1:])
+
+    if not args:
+        parser.error('A package path is required.')
+    if not opts.destdir:
+        parser.error('An output directory is required.')
+    rootpath, excludes = args[0], args[1:]
+    if not path.isdir(rootpath):
+        print >>sys.stderr, '%s is not a directory.' % rootpath
+        sys.exit(1)
+    if not path.isdir(opts.destdir):
+        print '%s is not a valid output directory.' % opts.destdir
+        sys.exit(1)
+    excludes = normalize_excludes(rootpath, excludes)
+    recurse_tree(rootpath, excludes, opts)

File sphinx/application.py

 
     Gracefully adapted from the TextPress system by Armin.
 
-    :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
+    :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS.
     :license: BSD, see LICENSE for details.
 """
 
 # List of all known core events. Maps name to arguments description.
 events = {
     'builder-inited': '',
+    'env-get-outdated': 'env, added, changed, removed',
     'env-purge-doc': 'env, docname',
     'source-read': 'docname, source text',
     'doctree-read': 'the doctree before being pickled',
         setattr(self.domains[domain], 'get_%s_index' % name, func)
 
     def add_object_type(self, directivename, rolename, indextemplate='',
-                        parse_node=None, ref_nodeclass=None, objname=''):
+                        parse_node=None, ref_nodeclass=None, objname='',
+                        doc_field_types=[]):
         StandardDomain.object_types[directivename] = \
             ObjType(objname or directivename, rolename)
         # create a subclass of GenericObject as the new directive
         new_directive = type(directivename, (GenericObject, object),
                              {'indextemplate': indextemplate,
-                              'parse_node': staticmethod(parse_node)})
+                              'parse_node': staticmethod(parse_node),
+                              'doc_field_types': doc_field_types})
         StandardDomain.directives[directivename] = new_directive
         # XXX support more options?
         StandardDomain.roles[rolename] = XRefRole(innernodeclass=ref_nodeclass)
         from sphinx.ext import autodoc
         autodoc.AutoDirective._special_attrgetters[type] = getter
 
+    def add_search_language(self, cls):
+        from sphinx.search import languages, SearchLanguage
+        assert isinstance(cls, SearchLanguage)
+        languages[cls.lang] = cls
+
 
 class TemplateBridge(object):
     """

File sphinx/builders/__init__.py

 
     Builder superclass for all builders.
 
-    :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
+    :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS.
     :license: BSD, see LICENSE for details.
 """
 
     name = ''
     # builder's output format, or '' if no document output is produced
     format = ''
+    # doctree versioning method
+    versioning_method = 'none'
 
     def __init__(self, app):
         self.env = app.env
+        self.env.set_versioning_method(self.versioning_method)
         self.srcdir = app.srcdir
         self.confdir = app.confdir
         self.outdir = app.outdir
         # add all toctree-containing files that may have changed
         for docname in list(docnames):
             for tocdocname in self.env.files_to_rebuild.get(docname, []):
-                docnames.add(tocdocname)
+                if tocdocname in self.env.found_docs:
+                    docnames.add(tocdocname)
         docnames.add(self.config.master_doc)
 
         self.info(bold('preparing documents... '), nonl=True)
     'changes':    ('changes', 'ChangesBuilder'),
     'linkcheck':  ('linkcheck', 'CheckExternalLinksBuilder'),
     'websupport': ('websupport', 'WebSupportBuilder'),
-    'gettext':    ('intl', 'MessageCatalogBuilder'),
+    'gettext':    ('gettext', 'MessageCatalogBuilder'),
 }

File sphinx/builders/changes.py