Michael Forbes avatar Michael Forbes committed 4303555 Merge

merged original -> autodoc

Comments (0)

Files changed (162)

 .*\.pyc
 .*\.egg
 .*\.so
-build/
-dist/
-tests/.coverage
-sphinx/pycode/Grammar.*pickle
-Sphinx.egg-info/
-doc/_build/
-TAGS
-\.ropeproject/
+.dir-locals.el
+\.DS_Store$
+^build/
+^dist/
+^tests/.coverage
+^sphinx/pycode/Grammar.*pickle
+^Sphinx.egg-info/
+^doc/_build/
+^TAGS
+^\.ropeproject/
 ^env/
 \.DS_Store$
+~$
+17af190a72e157f767e30a284f49bdcd2b5a3689 0.1.61611
+6d93c72d97d9e3cc7d2f3c03f279af0c7b1e85ff 0.1.61798
+1f4cba6a285ae9042762fb7cdcf88c6db55b9da7 0.1.61843
+51b03882bb4ccf0eb79facc9907ecd33405adcd8 0.1.61945
+230902d92af32355048ccf098736b002f2acb900 0.1.61950
+bb6452b7d1aaa94232f2508f75c2abeb48bd6a16 0.2
+1aebc142e92bdb9c990d3223cbaf99812fc59770 0.3
+9086e80b87408ae86519d36167ec2d2cd9c4291b 0.4
 83433c206e7f0d2a58243e2305f7253d172dce45 0.5
 dfe5aae7c8addea437d90fd3ba72f46ae8d95c53 0.5.1
 f00273402c9207f045270e472dde6324f1f3f4a5 0.5.2b1
+24762d857a192097f813818c4ff462f3bb32015f 0.5.2
 62a2a4c22b6ebb89e1277c6f29ba8ce9f0d43edd 0.6b1
-24762d857a192097f813818c4ff462f3bb32015f 0.5.2
 20f4a9ab90daee8523e00476a5a222d3a2bfea15 0.6
 fd52839b069b7127862811d105e0469b1a0c6608 0.6.1
 4be5ab5141779a1193b4f4b98c13700bd39d1a8c 0.6.2
 447109cf9b01d9ce79f78a725994080e79103cce 0.6.3
-9086e80b87408ae86519d36167ec2d2cd9c4291b 0.4
-1aebc142e92bdb9c990d3223cbaf99812fc59770 0.3
-bb6452b7d1aaa94232f2508f75c2abeb48bd6a16 0.2
-230902d92af32355048ccf098736b002f2acb900 0.1.61950
-51b03882bb4ccf0eb79facc9907ecd33405adcd8 0.1.61945
-1f4cba6a285ae9042762fb7cdcf88c6db55b9da7 0.1.61843
-6d93c72d97d9e3cc7d2f3c03f279af0c7b1e85ff 0.1.61798
-17af190a72e157f767e30a284f49bdcd2b5a3689 0.1.61611
 24a2061063212f1951507a35ed589a55cd9dd962 0.6.4
 f76fb0be8011dbecec8f39fba791feca24351bfb 0.6.5
 * Martin Mahner -- nature theme
 * Will Maier -- directory HTML builder
 * Roland Meister -- epub builder
+* Daniel Neuhäuser -- JavaScript domain
 * Christopher Perkins -- autosummary integration
 * Benjamin Peterson -- unittests
+* T. Powers -- HTML output improvements
 * Stefan Seefeld -- toctree improvements
 * Antonio Valentino -- qthelp builder
 * Pauli Virtanen -- autodoc improvements, autosummary extension
 * Stefan van der Walt -- autosummary extension
+* Barry Warsaw -- setup command improvements
 * Sebastian Wiesner -- image handling, distutils support
 
 Many thanks for all contributions!
 Release 1.0 (in development)
 ============================
 
+* Support for domains has been added.  A domain is a collection of
+  directives and roles that all describe objects belonging together,
+  e.g. elements of a programming language.  Builtin domains are
+  provided for Python and C objects.
+
+* Added a JavaScript domain.
+
+* Support for docutils 0.4 has been removed.
+
+* Added a manual page builder.
+
+* Added support for source ordering of members in autodoc, with
+  ``autodoc_member_order = 'bysource'``.
+
+* In HTML output, inline roles now get a CSS class with their name,
+  allowing styles to customize their appearance.  Domain-specific
+  roles get two classes, ``domain`` and ``domain-rolename``.
+
+* New more compact doc field syntax is now recognized:
+  ``:param type name: description``.
+
+* Added a "nitpicky" mode that emits warnings for all missing
+  references.  It is activated by the ``-n`` command-line switch
+  or the ``nitpicky`` config value.
+
+* Added the ``viewcode`` extension.
+
+* Added ``html-collect-pages`` event.
+
 * Sphinx now requires Jinja2 version 2.2 or greater.
 
+* Added Turkish translation, thanks to Firat Ozgul.
+
 * Added ``needs_sphinx`` config value and ``Sphinx.require_sphinx``
   application API function.
 
 
 * Added ``tab-width`` option to ``literalinclude`` directive.
 
+* Added ``rst_prolog`` config value.
+
+* Added ``html_secnumber_suffix`` config value to control section
+  numbering format.
+
+* Added ``html_compact_lists`` config value to control docutils'
+  compact lists feature.
+
 * The ``html_sidebars`` config value can now contain patterns as
   keys, and the values can be lists that explicitly select which
   sidebar templates should be rendered.  That means that the builtin
 
 * Added new HTML theme ``scrolls``, created by Armin Ronacher.
 
+* The ``toctree()`` callable in templates now has a ``maxdepth``
+  keyword argument to control the depth of the generated tree.
+
+* Added Catalan translation, thanks to Pau Fernández.
+
 * Added ``html_output_encoding`` config value.
 
 * #200: Added ``Sphinx.add_stylesheet()``.
 Release 0.6.6 (in development)
 ==============================
 
+* #387: Fix the display of search results in ``dirhtml`` output.
+
+* #376: In autodoc, fix display of parameter defaults containing
+  backslashes.
+
+* #370: Fix handling of complex list item labels in LaTeX output.
+
+* #374: Make the ``doctest_path`` config value of the doctest
+  extension actually work.
+
+* Fix the handling of multiple toctrees when creating the global
+  TOC for the ``toctree()`` template function.
+
+* Fix the handling of hidden toctrees when creating the global TOC
+  for the ``toctree()`` template function.
+
+* Fix the handling of nested lists in the text writer.
+
+* #362: In autodoc, check for the existence of ``__self__`` on
+  function objects before accessing it.
+
+* #353: Strip leading and trailing whitespace when extracting
+  search words in the search function.
+
 
 Release 0.6.5 (Mar 01, 2010)
 ============================
 * Bazaar: http://doc.bazaar.canonical.com/en/
 * Chaco: http://code.enthought.com/projects/chaco/docs/html/
 * Djagios: http://djagios.org/
+* GetFEM++: http://home.gna.org/getfem/
 * GPAW: https://wiki.fysik.dtu.dk/gpaw/
 * Grok: http://grok.zope.org/doc/current/
 * IFM: http://fluffybunny.memebot.com/ifm-docs/index.html
 Documentation using another builtin theme
 -----------------------------------------
 
+* 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)
 * pip: http://pip.openplans.org/ (nature)
 Documentation using a custom theme/integrated in a site
 -------------------------------------------------------
 
+* Blinker: http://discorporate.us/projects/Blinker/docs/
 * Django: http://docs.djangoproject.com/
 * GeoServer: http://docs.geoserver.org/
 * Glashammer: http://glashammer.org/
 check:
 	@$(PYTHON) utils/check_sources.py -i build -i dist -i sphinx/style/jquery.js \
 		-i sphinx/pycode/pgen2 -i sphinx/util/smartypants.py -i .ropeproject \
-		-i doc/_build -i ez_setup.py -i tests/path.py -i tests/coverage.py .
+		-i doc/_build -i ez_setup.py -i tests/path.py -i tests/coverage.py -i env .
 
 clean: clean-pyc clean-patchfiles
 
 PAPEROPT_a4      = -D latex_paper_size=a4
 PAPEROPT_letter  = -D latex_paper_size=letter
 ALLSPHINXOPTS = -d _build/doctrees $(PAPEROPT_$(PAPER)) \
-                $(SPHINXOPTS) .
+                $(SPHINXOPTS) $(O) .
 
-.PHONY: help clean html dirhtml pickle htmlhelp qthelp latex changes linkcheck doctest
+.PHONY: help clean html dirhtml pickle htmlhelp qthelp latex changes linkcheck doctest man
 
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
 	@echo "  htmlhelp  to make HTML files and a HTML help project"
 	@echo "  epub      to make an epub file"
 	@echo "  latex     to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  man       to make manual pages"
 	@echo "  changes   to make an overview over all changed/added/deprecated items"
 	@echo "  linkcheck to check all external links for integrity"
 
 	@echo
 	@echo "Build finished."
 
+man:
+	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) _build/man
+	@echo
+	@echo "Build finished."
+
 pickle:
 	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) _build/pickle
 

doc/_templates/index.html

   <h1>Welcome</h1>
 
   <div class="quotebar">
-    <p>What users say:</p>
+    <p><em>What users say:</em></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, 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>, 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>It was originally created for <a href="http://docs.python.org/dev/">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
+    course, this site is also created from reStructuredText sources using
+    Sphinx!
   </p>
   <p>
-    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:
+    Sphinx is under constant development.  The following features are present,
+    work fine and can be seen &#8220;in action&#8221; in the Python docs:
   </p>
   <ul>
-    <li><b>Output formats:</b> HTML (including Windows HTML Help) and LaTeX, for
-    printable PDF versions</li>
+    <li><b>Output formats:</b> HTML (including Windows HTML Help), LaTeX (for
+      printable PDF versions), manual pages, plain text</li>
     <li><b>Extensive cross-references:</b> semantic markup and automatic links
-    for functions, classes, glossary terms and similar pieces of information</li>
+      for functions, classes, citations, glossary terms and similar pieces of
+      information</li>
     <li><b>Hierarchical structure:</b> easy definition of a document tree, with
-    automatic links to siblings, parents and children</li>
+      automatic links to siblings, parents and children</li>
     <li><b>Automatic indices:</b> general index as well as a module index</li>
     <li><b>Code handling:</b> automatic highlighting using the <a
-    href="http://pygments.org">Pygments</a> highlighter</li>
+      href="http://pygments.org">Pygments</a> highlighter</li>
     <li><b>Extensions:</b> automatic testing of code snippets, inclusion of
-    docstrings from Python modules, and more</li>
+      docstrings from Python modules (API docs), and more</li>
   </ul>
   <p>
     Sphinx uses <a href="http://docutils.sf.net/rst.html">reStructuredText</a>
     suite, the <a href="http://docutils.sf.net/">Docutils</a>.
   </p>
 
-  <h2>Examples</h2>
-  <p>
-    The <a href="http://docs.python.org/dev/">Python documentation</a> and
-    this page are different examples of Sphinx in use.
-    You can also download PDF versions of the Sphinx documentation:
-    a <a href="http://sphinx.pocoo.org/sphinx.pdf">version</a> generated from
-    the LaTeX Sphinx produces, and a
-    <a href="http://sphinx.pocoo.org/sphinx-rst2pdf.pdf">version</a> generated by rst2pdf.
-  </p>
-  <p>
-    For examples of how Sphinx source files look, use the &#8220;Show source&#8221;
-    links on all pages of the documentation apart from this welcome page.
-  </p>
-  <p>Links to more documentation generated with Sphinx can be found on the
-    <a href="{{ pathto("examples") }}">Projects using Sphinx</a> page.
-  </p>
-
   <h2>Documentation</h2>
 
   <table class="contentstable" align="center" style="margin-left: 30px"><tr>
     <td width="50%">
+      <p class="biglink"><a class="biglink" href="{{ pathto("tutorial") }}">First steps with Sphinx</a><br/>
+         <span class="linkdescr">overview of basic tasks</span></p>
       <p class="biglink"><a class="biglink" href="{{ pathto("contents") }}">Contents</a><br/>
          <span class="linkdescr">for a complete overview</span></p>
+    </td><td width="50%">
       <p class="biglink"><a class="biglink" href="{{ pathto("search") }}">Search page</a><br/>
          <span class="linkdescr">search the documentation</span></p>
-    </td><td width="50%">
       <p class="biglink"><a class="biglink" href="{{ pathto("genindex") }}">General Index</a><br/>
          <span class="linkdescr">all functions, classes, terms</span></p>
-      <p class="biglink"><a class="biglink" href="{{ pathto("modindex") }}">Module Index</a><br/>
-         <span class="linkdescr">quick access to all documented modules</span></p>
     </td></tr>
   </table>
 
+  <p>
+    You can also download PDF versions of the Sphinx documentation:
+    a <a href="http://sphinx.pocoo.org/sphinx.pdf">version</a> generated from
+    the LaTeX Sphinx produces, and
+    a <a href="http://sphinx.pocoo.org/sphinx-rst2pdf.pdf">version</a> generated
+    by rst2pdf.
+  </p>
+
+  <h2>Examples</h2>
+  <p>Links to documentation generated with Sphinx can be found on the
+    <a href="{{ pathto("examples") }}">Projects using Sphinx</a> page.
+  </p>
+  <p>
+    For examples of how Sphinx source files look, use the &#8220;Show
+    source&#8221; links on all pages of the documentation apart from this
+    welcome page.
+  </p>
+
   <p>You may also be interested in the very nice
     <a href="http://matplotlib.sourceforge.net/sampledoc/">tutorial</a> on how to
     create a customized documentation using Sphinx written by the matplotlib

doc/_templates/layout.html

 
 {% block rootrellink %}
         <li><a href="{{ pathto('index') }}">Sphinx home</a>&nbsp;|&nbsp;</li>
-        <li><a href="{{ pathto('contents') }}">Documentation</a>&raquo;</li>
+        <li><a href="{{ pathto('contents') }}">Documentation</a>
+          &raquo;</li>
 {% endblock %}
 
 {% block header %}
 .. class:: QtHelpBuilder
 
    This builder produces the same output as the standalone HTML builder, but
-   also generates Qt help collection support files that allow
+   also generates `Qt help`_ collection support files that allow
    the Qt collection generator to compile them.
 
    Its name is ``qthelp``.
 
+   .. _Qt help: http://doc.trolltech.com/4.6/qthelp-framework.html
+
 .. module:: sphinx.builders.devhelp
 .. class:: DevhelpBuilder
 
 Note that a direct PDF builder using ReportLab is available in `rst2pdf
 <http://rst2pdf.googlecode.com>`_ version 0.12 or greater.  You need to add
 ``'rst2pdf.pdfbuilder'`` to your :confval:`extensions` to enable it, its name is
-``pdf``.
+``pdf``.  Refer to the `rst2pdf manual
+<http://lateral.netmanagers.com.ar/static/manual.pdf>`_ for details.
 
 .. module:: sphinx.builders.text
 .. class:: TextBuilder
 
    .. versionadded:: 0.4
 
+.. module:: sphinx.builders.manpage
+.. class:: ManualPageBuilder
+
+   This builder produces manual pages in the groff format.  You have to specify
+   which documents are to be included in which manual pages via the
+   :confval:`man_pages` configuration value.
+
+   Its name is ``man``.
+
+   .. note::
+
+      This builder requires the docutils manual page writer, which is only
+      available as of docutils 0.6.
+
+   .. versionadded:: 1.0
+
 .. currentmodule:: sphinx.builders.html
 .. class:: SerializingHTMLBuilder
 
    (`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`_
+   A concrete subclass of this builder serializing to the `PHP serialization`_
    format could look like this::
 
         import phpserialize
 .. module:: sphinx.builders.changes
 .. class:: ChangesBuilder
 
-   This builder produces an HTML overview of all :dir:`versionadded`,
-   :dir:`versionchanged` and :dir:`deprecated` directives for the current
+   This builder produces an HTML overview of all :rst:dir:`versionadded`,
+   :rst:dir:`versionchanged` and :rst:dir:`deprecated` directives for the current
    :confval:`version`.  This is useful to generate a ChangeLog file, for
    example.
 
    ``project``, ``copyright``, ``release``, ``version``
       The same values as given in the configuration file.
 
-   ``style``, ``use_modindex``
-      :confval:`html_style` and :confval:`html_use_modindex`, respectively.
+   ``style``
+      :confval:`html_style`.
 
    ``last_updated``
       Date of last build.
 ``environment.pickle``
    The build environment.  This is always a pickle file, independent of the
    builder and a copy of the environment that was used when the builder was
-   started.  (XXX: document common members)
+   started.
 
-   Unlike the other pickle files this pickle file requires that the sphinx
-   module is available on unpickling.
+   .. todo:: Document common members.
+
+   Unlike the other pickle files this pickle file requires that the ``sphinx``
+   package is available on unpickling.

doc/concepts.rst

-.. highlight:: rest
-
-.. _concepts:
-
-Sphinx concepts
-===============
-
-Document names
---------------
-
-Since the reST source files can have different extensions (some people like
-``.txt``, some like ``.rst`` -- the extension can be configured with
-:confval:`source_suffix`) and different OSes have different path separators,
-Sphinx abstracts them: all "document names" are relative to the :term:`source
-directory`, the extension is stripped, and path separators are converted to
-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
-------------
-
-.. index:: pair: table of; contents
-
-Since reST does not have facilities to interconnect several documents, or split
-documents into multiple output files, Sphinx uses a custom directive to add
-relations between the single files the documentation is made of, as well as
-tables of contents.  The ``toctree`` directive is the central element.
-
-.. directive:: toctree
-
-   This directive inserts a "TOC tree" at the current location, using the
-   individual TOCs (including "sub-TOC trees") of the documents given in the
-   directive body (whose path is relative to the document the directive occurs
-   in).  A numeric ``maxdepth`` option may be given to indicate the depth of the
-   tree; by default, all levels are included. [#]_
-
-   Consider this example (taken from the Python docs' library reference index)::
-
-      .. toctree::
-         :maxdepth: 2
-
-         intro
-         strings
-         datatypes
-         numeric
-         (many more documents listed here)
-
-   This accomplishes two things:
-
-   * Tables of contents from all those documents are inserted, with a maximum
-     depth of two, that means one nested heading.  ``toctree`` directives in
-     those documents are also taken into account.
-   * Sphinx knows that the relative order of the documents ``intro``,
-     ``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
-   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).
-
-   If you want only the titles of documents in the tree to show up, not other
-   headings of the same level, you can use the ``titlesonly`` option::
-
-      .. toctree::
-         :titlesonly:
-
-         foo
-         bar
-
-   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::
-
-      .. toctree::
-         :glob:
-
-         intro*
-         recipe/*
-         *
-
-   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
-   be reachable through standard navigation.  Use :confval:`unused_docs` to
-   explicitly exclude documents from building, and :confval:`exclude_trees` to
-   exclude whole directories.
-
-   The "master document" (selected by :confval:`master_doc`) is the "root" of
-   the TOC tree hierarchy.  It can be used as the documentation's main page, or
-   as a "full table of contents" if you don't give a ``maxdepth`` option.
-
-   .. versionchanged:: 0.3
-      Added "globbing" option.
-
-   .. versionchanged:: 0.6
-      Added "numbered" and "hidden" options as well as external links and
-      support for "self" references.
-
-   .. versionchanged:: 1.0
-      Added "titlesonly" option.
-
-
-Special names
--------------
-
-Sphinx reserves some document names for its own use; you should not try to
-create documents with these names -- it will cause problems.
-
-The special document names (and pages generated for them) are:
-
-* ``genindex``, ``modindex``, ``search``
-
-  These are used for the general index, the module index, and the search page,
-  respectively.
-
-  The general index is populated with entries from modules, all index-generating
-  :ref:`description units <desc-units>`, and from :dir:`index` directives.
-
-  The module index contains one entry per :dir:`module` directive.
-
-  The search page contains a form that uses the generated JSON search index and
-  JavaScript to full-text search the generated documents for search words; it
-  should work on every major browser that supports modern JavaScript.
-
-* every name beginning with ``_``
-
-  Though only few such names are currently used by Sphinx, you should not create
-  documents or document-containing directories with such names.  (Using ``_`` as
-  a prefix for a custom template directory is fine.)
-
-
-.. rubric:: Footnotes
-
-.. [#] The ``maxdepth`` option does not apply to the LaTeX writer, where the
-       whole table of contents will always be presented at the begin of the
-       document, and its depth is controlled by the ``tocdepth`` counter, which
-       you can reset in your :confval:`latex_preamble` config value using
-       e.g. ``\setcounter{tocdepth}{2}``.
-
-.. [#] A note on available globbing syntax: you can use the standard shell
-       constructs ``*``, ``?``, ``[...]`` and ``[!...]`` with the feature that
-       these all don't match slashes.  A double star ``**`` can be used to match
-       any sequence of characters *including* slashes.
 import sphinx
 
 extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.todo',
-              'sphinx.ext.autosummary']
+              'sphinx.ext.autosummary', 'sphinx.ext.extlinks']
 
 master_doc = 'contents'
 templates_path = ['_templates']
 copyright = '2007-2010, Georg Brandl'
 version = sphinx.__released__
 release = version
-
 show_authors = True
 
 html_theme = 'sphinxdoc'
     'fontpkg': '\\usepackage{palatino}',
 }
 
+autodoc_member_order = 'groupwise'
 todo_include_todos = True
+extlinks = {'rstref': ('http://docutils.sourceforge.net/docs/ref/rst/'
+                       'restructuredtext.html#%s', ''),
+            'rstrole': ('http://docutils.sourceforge.net/docs/ref/rst/'
+                        'roles.html#%s', ''),
+            'rstdir': ('http://docutils.sourceforge.net/docs/ref/rst/'
+                       'directives.html#%s', '')}
+
+man_pages = [
+    ('contents', 'sphinx-all', 'Sphinx documentation generator system manual',
+     'Georg Brandl', 1),
+    ('man/sphinx-build', 'sphinx-build', 'Sphinx documentation generator tool',
+     '', 1),
+    ('man/sphinx-quickstart', 'sphinx-quickstart', 'Sphinx documentation '
+     'template generator', '', 1),
+]
 
 
 # -- Extension interface -------------------------------------------------------
 
 from sphinx import addnodes
 
-dir_sig_re = re.compile(r'\.\. ([^:]+)::(.*)$')
-
-def parse_directive(env, sig, signode):
-    if not sig.startswith('.'):
-        dec_sig = '.. %s::' % sig
-        signode += addnodes.desc_name(dec_sig, dec_sig)
-        return sig
-    m = dir_sig_re.match(sig)
-    if not m:
-        signode += addnodes.desc_name(sig, sig)
-        return sig
-    name, args = m.groups()
-    dec_name = '.. %s::' % name
-    signode += addnodes.desc_name(dec_name, dec_name)
-    signode += addnodes.desc_addname(args, args)
-    return name
-
-
-def parse_role(env, sig, signode):
-    signode += addnodes.desc_name(':%s:' % sig, ':%s:' % sig)
-    return sig
-
 
 event_sig_re = re.compile(r'([a-zA-Z-]+)\s*\((.*)\)')
 
 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('role', 'role', 'pair: %s; role', parse_role)
     app.add_description_unit('confval', 'confval',
-                             'pair: %s; configuration value')
+                             objname='configuration value',
+                             indextemplate='pair: %s; configuration value')
     app.add_description_unit('event', 'event', 'pair: %s; event', parse_event)
 .. highlightlang:: python
 
+.. _build-config:
+
 The build configuration file
 ============================
 
 .. confval:: master_doc
 
    The document name of the "master" document, that is, the document that
-   contains the root :dir:`toctree` directive.  Default is ``'contents'``.
+   contains the root :rst:dir:`toctree` directive.  Default is ``'contents'``.
 
 .. confval:: exclude_patterns
 
 
    Directories in which to search for additional Sphinx message catalogs (see
    :confval:`language`), relative to the source directory.  The directories on
-   this path are searched by the standard :mod:`gettext` module for a domain of
-   ``sphinx``; so if you add the directory :file:`./locale` to this settting,
-   the message catalogs must be in
+   this path are searched by the standard :mod:`gettext` module for a text
+   domain of ``sphinx``; so if you add the directory :file:`./locale` to this
+   settting, the message catalogs (compiled from ``.po`` format using
+   :program:`msgfmt`) must be in
    :file:`./locale/{language}/LC_MESSAGES/sphinx.mo`.
 
    The default is ``[]``.
 
    .. versionadded:: 0.6
 
+.. confval:: rst_prolog
+
+   A string of reStructuredText that will be included at the beginning of every
+   source file that is read.
+
+   .. versionadded:: 1.0
+
+.. confval:: default_domain
+
+   .. index:: default; domain
+
+   The name of the default :ref:`domain <domains>`.  Can also be ``None`` to
+   disable a default domain.  The default is ``'py'``.
+
+   .. versionadded:: 1.0
+
 .. 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".
-   The default is ``None``, which doesn't reassign the default role.
+   ``'py:obj'`` to make ```filter``` a cross-reference to the Python function
+   "filter".  The default is ``None``, which doesn't reassign the default role.
 
    The default role can always be set within individual documents using the
-   standard reST :dir:`default-role` directive.
+   standard reST :rst:dir:`default-role` directive.
 
    .. versionadded:: 0.4
 
 
    .. versionadded:: 0.5
 
-.. confval:: modindex_common_prefix
+.. confval:: needs_sphinx
 
-   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
-
-.. confval:: trim_doctest_flags
-
-   If true, doctest flags (comments looking like ``# doctest: FLAG, ...``) at
-   the ends of lines are removed for all code blocks showing interactive Python
-   sessions (i.e. doctests).  Default is true.  See the extension
-   :mod:`~sphinx.ext.doctest` for more possibilities of including doctests.
+   If set to a ``major.minor`` version string like ``'1.1'``, Sphinx will
+   compare it with its version and refuse to build if it is too old.  Default is
+   no requirement.
 
    .. versionadded:: 1.0
 
-.. confval:: needs_sphinx
+.. confval:: nitpicky
 
-   If set to a ``major.minor`` version string like ``'1.1'``, Sphinx will
-   compare it with its version and refuse to build if it is too old.
+   If true, Sphinx will warn about *all* references where the target cannot be
+   found.  Default is ``False``.  You can activate this mode temporarily using
+   the :option:`-n` command-line switch.
 
    .. versionadded:: 1.0
 
+.. confval:: global_config_file
 
+   If this is specified, then this file will be executed and used to
+   provide default values.  Values in the local config file will
+   overwrite these unless the values are lists or dicts.  For lists
+   the local values will be appended (so they take effect last).  For
+   dict, any local keys will overwrite the global keys.  These
+   defaults are processed after the local :file:`conf.py` is read, so
+   the defaults are not available during the processing of :file:`conf.py`.
+   
+   This is useful if you need to specify site-specific paths
+   etc. however consider that will make it difficult to distribute
+   your documentation because you will need to explicitly include this
+   file.
+   
+   .. versionadded:: sphinx-mmf
+  
 Project information
 -------------------
 
 
    Currently supported languages are:
 
+   * ``ca`` -- Catalan
    * ``cs`` -- Czech
    * ``de`` -- German
    * ``en`` -- English
    * ``pt_BR`` -- Brazilian Portuguese
    * ``ru`` -- Russian
    * ``sl`` -- Slovenian
+   * ``tr`` -- Turkish
    * ``uk_UA`` -- Ukrainian
    * ``zh_CN`` -- Simplified Chinese
    * ``zh_TW`` -- Traditional Chinese
 .. confval:: add_module_names
 
    A boolean that decides whether module names are prepended to all
-   :term:`description unit` titles, e.g. for :dir:`function` directives.
-   Default is ``True``.
+   :term:`object` names (for object types where a "module" of some kind is
+   defined), e.g. for :rst:dir:`function` directives.  Default is ``True``.
 
 .. confval:: show_authors
 
-   A boolean that decides whether :dir:`moduleauthor` and :dir:`sectionauthor`
+   A boolean that decides whether :rst:dir:`moduleauthor` and :rst:dir:`sectionauthor`
    directives produce any output in the built files.
 
+.. confval:: modindex_common_prefix
+
+   A list of prefixes that are ignored for sorting the Python 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
+
 .. confval:: trim_footnote_reference_space
 
    Trim spaces before footnote references that are necessary for the reST parser
 
    .. versionadded:: 0.6
 
+.. confval:: trim_doctest_flags
+
+   If true, doctest flags (comments looking like ``# doctest: FLAG, ...``) at
+   the ends of lines are removed for all code blocks showing interactive Python
+   sessions (i.e. doctests).  Default is true.  See the extension
+   :mod:`~sphinx.ext.doctest` for more possibilities of including doctests.
+
+   .. versionadded:: 1.0
+
 
 .. _html-options:
 
          ... old template content ...
          {% endblock %}
 
+.. confval:: html_domain_indices
+
+   If true, generate domain-specific indices in addition to the general index.
+   For e.g. the Python domain, this is the global module index.  Default is
+   ``True``.
+
+   This value can be a bool or a list of index names that should be generated.
+   To find out the index name for a specific index, look at the HTML file name.
+   For example, the Python module index has the name ``'py-modindex'``.
+
+   .. versionadded:: 1.0
+
 .. confval:: html_use_modindex
 
    If true, add a module index to the HTML documents.   Default is ``True``.
 
+   .. deprecated:: 1.0
+      Use :confval:`html_domain_indices`.
+
 .. confval:: html_use_index
 
    If true, add an index to the HTML documents.  Default is ``True``.
 
    .. versionadded:: 1.0
 
+.. confval:: html_compact_lists
+
+   If true, list items containing only a single paragraph will not be rendered
+   with a ``<p>`` element.  This is standard docutils behavior.  Default:
+   ``True``.
+
+   .. versionadded:: 1.0
+
+.. confval:: html_secnumber_suffix
+
+   Suffix for section numbers.  Default: ``". "``.  Set to ``" "`` to suppress
+   the final dot on section numbers.
+
+   .. versionadded:: 1.0
+
 .. confval:: htmlhelp_basename
 
    Output file base name for HTML help builder.  Default is ``'pydoc'``.
 
    A list of document names to append as an appendix to all manuals.
 
+.. confval:: latex_domain_indices
+
+   If true, generate domain-specific indices in addition to the general index.
+   For e.g. the Python domain, this is the global module index.  Default is
+   ``True``.
+
+   This value can be a bool or a list of index names that should be generated,
+   like for :confval:`html_domain_indices`.
+
+   .. versionadded:: 1.0
+
 .. confval:: latex_use_modindex
 
    If true, add a module index to LaTeX documents.   Default is ``True``.
 
+   .. deprecated:: 1.0
+      Use :confval:`latex_domain_indices`.
+
 .. confval:: latex_elements
 
    .. versionadded:: 0.5
      ``'logo'``
      ``'releasename'``
      ``'makeindex'``
-     ``'makemodindex'``
      ``'shorthandoff'``
-     ``'printmodindex'``
 
 .. confval:: latex_docclass
 
       Use the ``'pointsize'`` key in the :confval:`latex_elements` value.
 
 
+.. _man-options:
+
+Options for manual page output
+------------------------------
+
+These options influence manual page output.
+
+.. confval:: man_pages
+
+   This value determines how to group the document tree into manual pages.  It
+   must be a list of tuples ``(startdocname, name, description, authors,
+   section)``, where the items are:
+
+   * *startdocname*: document name that is the "root" of the manual page.  All
+     documents referenced by it in TOC trees will be included in the manual file
+     too.  (If you want one master manual page, use your :confval:`master_doc`
+     here.)
+   * *name*: name of the manual page.  This should be a short string without
+     spaces or special characters.  It is used to determine the file name as
+     well as the name of the manual page (in the NAME section).
+   * *description*: description of the manual page.  This is used in the NAME
+     section.
+   * *authors*: A list of strings with authors, or a single string.  Can be
+     an empty string or list if you do not want to automatically generate
+     an AUTHORS section in the manual page.
+   * *section*: The manual page section.  Used for the output file name as well
+     as in the manual page header.
+
+   .. versionadded:: 1.0
+
+
 .. rubric:: Footnotes
 
 .. [1] A note on available globbing syntax: you can use the standard shell
    :maxdepth: 2
 
    intro
-   concepts
+   tutorial
+   invocation
    rest
    markup/index
+   domains
    builders
    config
    theming
+.. highlight:: rst
+
+.. _domains:
+
+Sphinx Domains
+==============
+
+.. versionadded:: 1.0
+
+What is a Domain?
+-----------------
+
+Originally, Sphinx was conceived for a single project, the documentation of the
+Python language.  Shortly afterwards, it was made available for everyone as a
+documentation tool, but the documentation of Python modules remained deeply
+built in -- the most fundamental directives, like ``function``, were designed
+for Python objects.  Since Sphinx has become somewhat popular, interest
+developed in using it for many different purposes: C/C++ projects, JavaScript,
+or even reStructuredText markup (like in this documentation).
+
+While this was always possible, it is now much easier to easily support
+documentation of projects using different programming languages or even ones not
+supported by the main Sphinx distribution, by providing a **domain** for every
+such purpose.
+
+A domain is a collection of markup (reStructuredText :term:`directive`\ s and
+:term:`role`\ s) to describe and link to :term:`object`\ s belonging together,
+e.g. elements of a programming language.  Directive and role names in a domain
+have names like ``domain:name``, e.g. ``py:function``.  Domains can also provide
+custom indices (like the Python Module Index).
+
+Having domains means that there are no naming problems when one set of
+documentation wants to refer to e.g. C++ and Python classes.  It also means that
+extensions that support the documentation of whole new languages are much easier
+to write.
+
+This section describes what the domains that come with Sphinx provide.  The
+domain API is documented as well, in the section :ref:`domain-api`.
+
+
+.. _basic-domain-markup:
+
+Basic Markup
+------------
+
+Most domains provide a number of :dfn:`object description directives`, used to
+describe specific objects provided by modules.  Each directive requires one or
+more signatures to provide basic information about what is being described, and
+the content should be the description.  The basic version makes entries in the
+general index; if no index entry is desired, you can give the directive option
+flag ``:noindex:``.  An example using a Python domain directive::
+
+   .. py:function:: spam(eggs)
+                    ham(eggs)
+      :noindex:
+
+      Spam or ham the foo.
+
+The domains also provide roles that link back to these object descriptions.  For
+example, to link to one of the functions described in the example above, you
+could say ::
+
+   The function :py:func:`spam` does a similar thing.
+
+As you can see, both directive and role names contain the domain name and the
+directive name.
+
+.. rubric:: Default Domain
+
+To avoid having to writing the domain name all the time when you e.g. only
+describe Python objects, a default domain can be selected with either the config
+value :confval:`default_domain` or this directive:
+
+.. rst:directive:: .. default-domain:: name
+
+   Select a new default domain.  While the :confval:`default_domain` selects a
+   global default, this only has an effect within the same file.
+
+If no other default is selected, the Python domain (named ``py``) is the default
+one, mostly for compatibility with documentation written for older versions of
+Sphinx.
+
+Directives and roles that belong to the default domain can be mentioned without
+giving the domain name, i.e. ::
+
+   .. function:: pyfunc()
+
+      Describes a Python function.
+
+   Reference to :func:`pyfunc`.
+
+
+Cross-referencing syntax
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+For cross-reference roles provided by domains, the same facilities exist as for
+general cross-references.  See :ref:`xref-syntax`.
+
+In short:
+
+* You may supply an explicit title and reference target: ``:role:`title
+  <target>``` will refer to *target*, but the link text will be *title*.
+
+* If you prefix the content with ``!``, no reference/hyperlink will be created.
+
+* If you prefix the content with ``~``, the link text will only be the last
+  component of the target.  For example, ``:py:meth:`~Queue.Queue.get``` will
+  refer to ``Queue.Queue.get`` but only display ``get`` as the link text.
+
+
+The Python Domain
+-----------------
+
+The Python domain (name **py**) provides the following directives for module
+declarations:
+
+.. rst:directive:: .. py:module:: name
+
+   This directive marks the beginning of the description of a module (or package
+   submodule, in which case the name should be fully qualified, including the
+   package name).  It does not create content (like e.g. :rst:dir:`py:class` does).
+
+   This directive will also cause an entry in the global module index.
+
+   The ``platform`` option, if present, is a comma-separated list of the
+   platforms on which the module is available (if it is available on all
+   platforms, the option should be omitted).  The keys are short identifiers;
+   examples that are in use include "IRIX", "Mac", "Windows", and "Unix".  It is
+   important to use a key which has already been used when applicable.
+
+   The ``synopsis`` option should consist of one sentence describing the
+   module's purpose -- it is currently only used in the Global Module Index.
+
+   The ``deprecated`` option can be given (with no value) to mark a module as
+   deprecated; it will be designated as such in various locations then.
+
+
+.. rst:directive:: .. py:currentmodule:: name
+
+   This directive tells Sphinx that the classes, functions etc. documented from
+   here are in the given module (like :rst:dir:`py:module`), but it will not create
+   index entries, an entry in the Global Module Index, or a link target for
+   :rst:role:`mod`.  This is helpful in situations where documentation for things in
+   a module is spread over multiple files or sections -- one location has the
+   :rst:dir:`py:module` directive, the others only :rst:dir:`py:currentmodule`.
+
+
+The following directives are provided for module and class contents:
+
+.. rst:directive:: .. py:data:: name
+
+   Describes global data in a module, including both variables and values used
+   as "defined constants."  Class and object attributes are not documented
+   using this environment.
+
+.. rst:directive:: .. py:exception:: name
+
+   Describes an exception class.  The signature can, but need not include
+   parentheses with constructor arguments.
+
+.. rst:directive:: .. py:function:: name(signature)
+
+   Describes a module-level function.  The signature should include the
+   parameters, enclosing optional parameters in brackets.  Default values can be
+   given if it enhances clarity; see :ref:`signatures`.  For example::
+
+      .. py:function:: Timer.repeat([repeat=3[, number=1000000]])
+
+   Object methods are not documented using this directive. Bound object methods
+   placed in the module namespace as part of the public interface of the module
+   are documented using this, as they are equivalent to normal functions for
+   most purposes.
+
+   The description should include information about the parameters required and
+   how they are used (especially whether mutable objects passed as parameters
+   are modified), side effects, and possible exceptions.  A small example may be
+   provided.
+
+.. rst:directive:: .. py:class:: name[(signature)]
+
+   Describes a class.  The signature can include parentheses with parameters
+   which will be shown as the constructor arguments.  See also
+   :ref:`signatures`.
+
+   Methods and attributes belonging to the class should be placed in this
+   directive's body.  If they are placed outside, the supplied name should
+   contain the class name so that cross-references still work.  Example::
+
+      .. py:class:: Foo
+         .. py:method:: quux()
+
+      -- or --
+
+      .. py:class:: Bar
+
+      .. py:method:: Bar.quux()
+
+   The first way is the preferred one.
+
+.. rst:directive:: .. py:attribute:: name
+
+   Describes an object data attribute.  The description should include
+   information about the type of the data to be expected and whether it may be
+   changed directly.
+
+.. rst:directive:: .. py:method:: name(signature)
+
+   Describes an object method.  The parameters should not include the ``self``
+   parameter.  The description should include similar information to that
+   described for ``function``.  See also :ref:`signatures`.
+
+.. rst:directive:: .. py:staticmethod:: name(signature)
+
+   Like :rst:dir:`py:method`, but indicates that the method is a static method.
+
+   .. versionadded:: 0.4
+
+.. rst:directive:: .. py:classmethod:: name(signature)
+
+   Like :rst:dir:`py:method`, but indicates that the method is a class method.
+
+   .. versionadded:: 0.6
+
+
+.. _signatures:
+
+Python Signatures
+~~~~~~~~~~~~~~~~~
+
+Signatures of functions, methods and class constructors can be given like they
+would be written in Python, with the exception that optional parameters can be
+indicated by brackets::
+
+   .. py:function:: compile(source[, filename[, symbol]])
+
+It is customary to put the opening bracket before the comma.  In addition to
+this "nested" bracket style, a "flat" style can also be used, due to the fact
+that most optional parameters can be given independently::
+
+   .. py:function:: compile(source[, filename, symbol])
+
+Default values for optional arguments can be given (but if they contain commas,
+they will confuse the signature parser).  Python 3-style argument annotations
+can also be given as well as return type annotations::
+
+   .. py:function:: compile(source : string[, filename, symbol]) -> ast object
+
+
+Info field lists
+~~~~~~~~~~~~~~~~
+
+.. versionadded:: 0.4
+
+Inside Python object description directives, reST field lists with these fields
+are recognized and formatted nicely:
+
+* ``param``, ``parameter``, ``arg``, ``argument``, ``key``, ``keyword``:
+  Description of a parameter.
+* ``type``: Type of a parameter.
+* ``raises``, ``raise``, ``except``, ``exception``: That (and when) a specific
+  exception is raised.
+* ``var``, ``ivar``, ``cvar``: Description of a variable.
+* ``returns``, ``return``: Description of the return value.
+* ``rtype``: Return type.
+
+The field names must consist of one of these keywords and an argument (except
+for ``returns`` and ``rtype``, which do not need an argument).  This is best
+explained by an example::
+
+   .. py:function:: format_exception(etype, value, tb[, limit=None])
+
+      Format the exception with a traceback.
+
+      :param etype: exception type
+      :param value: exception value
+      :param tb: traceback object
+      :param limit: maximum number of stack frames to show
+      :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])
+      :noindex:
+
+      Format the exception with a traceback.
+
+      :param etype: exception type
+      :param value: exception value
+      :param tb: traceback object
+      :param limit: maximum number of stack frames to show
+      :type limit: integer or None
+      :rtype: list of strings
+
+
+Cross-referencing Python objects
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following roles refer to objects in modules and are possibly hyperlinked if
+a matching identifier is found:
+
+.. rst:role:: py:mod
+
+   Reference a module; a dotted name may be used.  This should also be used for
+   package names.
+
+.. rst:role:: py:func
+
+   Reference a Python function; dotted names may be used.  The role text needs
+   not include trailing parentheses to enhance readability; they will be added
+   automatically by Sphinx if the :confval:`add_function_parentheses` config
+   value is true (the default).
+
+.. rst:role:: py:data
+
+   Reference a module-level variable.
+
+.. rst:role:: py:const
+
+   Reference a "defined" constant.  This may be a C-language ``#define`` or a
+   Python variable that is not intended to be changed.
+
+.. rst:role:: py:class
+
+   Reference a class; a dotted name may be used.
+
+.. rst:role:: py:meth
+
+   Reference a method of an object.  The role text can include the type name and
+   the method name; if it occurs within the description of a type, the type name
+   can be omitted.  A dotted name may be used.
+
+.. rst:role:: py:attr
+
+   Reference a data attribute of an object.
+
+.. rst:role:: py:exc
+
+   Reference an exception.  A dotted name may be used.
+
+.. rst:role:: py:obj
+
+   Reference an object of unspecified type.  Useful e.g. as the
+   :confval:`default_role`.
+
+   .. versionadded:: 0.4
+
+The name enclosed in this markup can include a module name and/or a class name.
+For example, ``:py:func:`filter``` could refer to a function named ``filter`` in
+the current module, or the built-in function of that name.  In contrast,
+``:py:func:`foo.filter``` clearly refers to the ``filter`` function in the
+``foo`` module.
+
+Normally, names in these roles are searched first without any further
+qualification, then with the current module name prepended, then with the
+current module and class name (if any) prepended.  If you prefix the name with a
+dot, this order is reversed.  For example, in the documentation of Python's
+:mod:`codecs` module, ``:py:func:`open``` always refers to the built-in
+function, while ``:py:func:`.open``` refers to :func:`codecs.open`.
+
+A similar heuristic is used to determine whether the name is an attribute of the
+currently documented class.
+
+
+The C Domain
+------------
+
+The C domain (name **c**) is suited for documentation of C API.
+
+.. rst:directive:: .. c:function:: type name(signature)
+
+   Describes a C function. The signature should be given as in C, e.g.::
+
+      .. c:function:: PyObject* PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)
+
+   This is also used to describe function-like preprocessor macros.  The names
+   of the arguments should be given so they may be used in the description.
+
+   Note that you don't have to backslash-escape asterisks in the signature, as
+   it is not parsed by the reST inliner.
+
+.. rst:directive:: .. c:member:: type name
+
+   Describes a C struct member. Example signature::
+
+      .. c:member:: PyObject* PyTypeObject.tp_bases
+
+   The text of the description should include the range of values allowed, how
+   the value should be interpreted, and whether the value can be changed.
+   References to structure members in text should use the ``member`` role.
+
+.. rst:directive:: .. c:macro:: name
+
+   Describes a "simple" C macro.  Simple macros are macros which are used for
+   code expansion, but which do not take arguments so cannot be described as
+   functions.  This is not to be used for simple constant definitions.  Examples
+   of its use in the Python documentation include :c:macro:`PyObject_HEAD` and
+   :c:macro:`Py_BEGIN_ALLOW_THREADS`.
+
+.. rst:directive:: .. c:type:: name
+
+   Describes a C type (whether defined by a typedef or struct). The signature
+   should just be the type name.
+
+.. rst:directive:: .. c:var:: type name
+
+   Describes a global C variable.  The signature should include the type, such
+   as::
+
+      .. c:var:: PyObject* PyClass_Type
+
+
+Cross-referencing C constructs
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following roles create cross-references to C-language constructs if they are
+defined in the documentation:
+
+.. rst:role:: c:data
+
+   Reference a C-language variable.
+
+.. rst:role:: c:func
+
+   Reference a C-language function. Should include trailing parentheses.
+
+.. rst:role:: c:macro
+
+   Reference a "simple" C macro, as defined above.
+
+.. rst:role:: c:type
+
+   Reference a C-language type.
+
+
+The C++ Domain
+--------------
+
+The C++ domain (name **cpp**) supports documenting C++ projects.
+
+The following directives are available:
+
+.. rst:directive:: .. cpp:class:: signatures
+               .. cpp:function:: signatures
+               .. cpp:member:: signatures
+               .. cpp:type:: signatures
+
+   Describe a C++ object.  Full signature specification is supported -- give the
+   signature as you would in the declaration.  Example::
+
+      .. cpp:function:: const int IntArray::operator[]
+
+         Describes the indexing operator of IntArrays.
+
+.. rst:directive:: .. cpp:namespace:: namespace
+
+   Select the current C++ namespace for the following objects.
+
+These roles link to the given object types:
+
+.. rst:role:: cpp:class
+          cpp:func
+          cpp:member
+          cpp:type
+
+   Reference a C++ object.  You can give the full signature (and need to, for
+   overloaded functions.)
+
+
+The Standard Domain
+-------------------
+
+The so-called "standard" domain collects all markup that doesn't warrant a
+domain of its own.  Its directives and roles are not prefixed with a domain
+name.
+
+The standard domain is also where custom object descriptions, added using the
+:func:`~sphinx.application.Sphinx.add_object_type` API, are placed.
+
+There is a set of directives allowing documenting command-line programs:
+
+.. rst:directive:: .. option:: name args, name args, ...
+
+   Describes a command line option or switch.  Option argument names should be
+   enclosed in angle brackets.  Example::
+
+      .. option:: -m <module>, --module <module>
+
+         Run a module as a script.
+
+   The directive will create a cross-reference target named after the *first*
+   option, referencable by :rst:role:`option` (in the example case, you'd use
+   something like ``:option:`-m```).
+
+.. rst:directive:: .. envvar:: name
+
+   Describes an environment variable that the documented code or program uses or
+   defines.  Referencable by :rst:role:`envvar`.
+
+.. rst:directive:: .. program:: name
+
+   Like :rst:dir:`py:currentmodule`, this directive produces no output.  Instead, it
+   serves to notify Sphinx that all following :rst:dir:`option` directives
+   document options for the program called *name*.
+
+   If you use :rst:dir:`program`, you have to qualify the references in your
+   :rst:role:`option` roles by the program name, so if you have the following
+   situation ::
+
+      .. program:: rm
+
+      .. option:: -r
+
+         Work recursively.
+
+      .. program:: svn
+
+      .. option:: -r revision
+
+         Specify the revision to work upon.
+
+   then ``:option:`rm -r``` would refer to the first option, while
+   ``:option:`svn -r``` would refer to the second one.
+
+   The program name may contain spaces (in case you want to document subcommands
+   like ``svn add`` and ``svn commit`` separately).
+
+   .. versionadded:: 0.5
+
+
+There is also a very generic object description directive, which is not tied to
+any domain:
+
+.. rst:directive:: .. describe:: text
+               .. object:: text
+
+   This directive produces the same formatting as the specific ones provided by
+   domains, but does not create index entries or cross-referencing targets.
+   Example::
+
+      .. describe:: PAPER
+
+         You can set this variable to select a paper size.
+
+
+The JavaScript Domain
+---------------------
+
+The JavaScript domain (name **js**) provides the following directives:
+
+.. rst:directive:: .. js:function:: name(signature)
+
+   Describes a JavaScript function, method or constructor.  If you want to
+   describe arguments as optional use square brackets as :ref:`documented
+   <signatures>` for Python signatures.
+
+   You can use fields to give more details about arguments and their expected
+   types, errors which may be thrown by the function, and the value being
+   returned::
+
+      .. js:function:: $.getJSON(href, callback[, errback])
+
+         :param string href: An URI to the location of the resource.
+         :param callback: Get's called with the object.
+         :param errback:
+             Get's called in case the request fails. And a lot of other
+             text so we need multiple lines
+         :throws SomeError: For whatever reason in that case.
+         :returns: Something
+
+   This is rendered as:
+
+      .. js:function:: $.getJSON(href, callback[, errback])
+
+        :param string href: An URI to the location of the resource.
+        :param callback: Get's called with the object.
+        :param errback:
+            Get's called in case the request fails. And a lot of other
+            text so we need multiple lines.
+        :throws SomeError: For whatever reason in that case.
+        :returns: Something
+
+.. rst:directive:: .. js:data:: name
+
+   Describes a global variable or constant.
+
+.. rst:directive:: .. js:attribute:: object.name
+
+   Describes the attribute *name* of *object*.
+
+These roles are provided to refer to the described objects:
+
+.. rst:role:: js:func
+          js:data
+          js:attr
+
+
+The reStructuredText domain
+---------------------------
+
+The reStructuredText domain (name **rst**) provides the following directives:
+
+.. rst:directive:: .. rst:directive:: name
+
+   Describes a reST directive.  The *name* can be a single directive name or
+   actual directive syntax (`..` prefix and `::` suffix) with arguments that
+   will be rendered differently.  For example::
+
+      .. rst:directive:: foo
+
+         Foo description.
+
+      .. rst:directive:: .. bar:: baz
+
+         Bar description.
+
+   will be rendered as:
+
+      .. rst:directive:: foo
+
+         Foo description.
+
+      .. rst:directive:: .. bar:: baz
+
+         Bar description.
+
+.. rst:directive:: .. rst:role:: name
+
+   Describes a reST role.  For example::
+
+      .. rst:role:: foo
+
+         Foo description.
+
+   will be rendered as:
+
+      .. rst:role:: foo
+
+         Foo description.
+
+These roles are provided to refer to the described objects:
+
+.. rst:role:: rst:dir
+              rst:role
+

doc/ext/appapi.rst

       ``'env'``) to a string.  However, booleans are still accepted and
       converted internally.
 
+.. method:: Sphinx.add_domain(domain)
+
+   Make the given *domain* (which must be a class; more precisely, a subclass of
+   :class:`~sphinx.domains.Domain`) known to Sphinx.
+
+   .. versionadded:: 1.0
+
+.. method:: Sphinx.override_domain(domain)
+
+   Make the given *domain* class known to Sphinx, assuming that there is already
+   a domain with its ``.name``.  The new domain must be a subclass of the
+   existing one.
+
+   .. versionadded:: 1.0
+
+.. method:: Sphinx.add_index_to_domain(domain, index)
+
+   Add a custom *index* class to the domain named *domain*.  *index* must be a
+   subclass of :class:`~sphinx.domains.Index`.
+
+   .. versionadded:: 1.0
+
 .. method:: Sphinx.add_event(name)
 
-   Register an event called *name*.
+   Register an event called *name*.  This is needed to be able to emit it.
 
 .. method:: Sphinx.add_node(node, **kwds)
 
    Register a Docutils node class.  This is necessary for Docutils internals.
    It may also be used in the future to validate nodes in the parsed documents.
 
-   Node visitor functions for the Sphinx HTML, LaTeX and text writers can be
-   given as keyword arguments: the keyword must be one or more of ``'html'``,
-   ``'latex'``, ``'text'``, the value a 2-tuple of ``(visit, depart)`` methods.
-   ``depart`` can be ``None`` if the ``visit`` function raises
-   :exc:`docutils.nodes.SkipNode`.  Example:
+   Node visitor functions for the Sphinx HTML, LaTeX, text and manpage writers
+   can be given as keyword arguments: the keyword must be one or more of
+   ``'html'``, ``'latex'``, ``'text'``, ``'man'``, the value a 2-tuple of
+   ``(visit, depart)`` methods.  ``depart`` can be ``None`` if the ``visit``
+   function raises :exc:`docutils.nodes.SkipNode`.  Example:
 
    .. code-block:: python
 
    Register a Docutils directive.  *name* must be the prospective directive
    name.  There are two possible ways to write a directive:
 
-   * In the docutils 0.4 style, *func* is the directive function.  *content*,
+   * In the docutils 0.4 style, *obj* is the directive function.  *content*,
      *arguments* and *options* are set as attributes on the function and
      determine whether the directive has content, arguments and options,
-     respectively.
+     respectively.  **This style is deprecated.**
 
    * In the docutils 0.5 style, *directiveclass* is the directive class.  It
      must already have attributes named *has_content*, *required_arguments*,
      instead which does the right thing even on docutils 0.4 (which doesn't
      support directive classes otherwise).
 
-   For example, the (already existing) :dir:`literalinclude` directive would be
+   For example, the (already existing) :rst:dir:`literalinclude` directive would be
    added like this:
 
    .. code-block:: python
    .. versionchanged:: 0.6
       Docutils 0.5-style directive classes are now supported.
 
+.. method:: Sphinx.add_directive_to_domain(domain, name, func, content, arguments, **options)
+            Sphinx.add_directive_to_domain(domain, name, directiveclass)
+
+   Like :meth:`add_directive`, but the directive is added to the domain named
+   *domain*.
+
+   .. versionadded:: 1.0
+
 .. method:: Sphinx.add_role(name, role)
 
    Register a Docutils role.  *name* must be the role name that occurs in the
    source, *role* the role function (see the `Docutils documentation
    <http://docutils.sourceforge.net/docs/howto/rst-roles.html>`_ on details).
 
+.. method:: Sphinx.add_role_to_domain(domain, name, role)
+
+   Like :meth:`add_role`, but the role is added to the domain named *domain*.
+
+   .. versionadded:: 1.0
+
 .. method:: Sphinx.add_generic_role(name, nodeclass)
 
    Register a Docutils role that does nothing but wrap its contents in the
 
    .. versionadded:: 0.6
 
-.. method:: Sphinx.add_description_unit(directivename, rolename, indextemplate='', parse_node=None, ref_nodeclass=None)
+.. method:: Sphinx.add_object_type(directivename, rolename, indextemplate='', parse_node=None, ref_nodeclass=None, objname='')
 
-   This method is a very convenient way to add a new type of information that
+   This method is a very convenient way to add a new :term:`object` type that
    can be cross-referenced.  It will do this:
 
-   * Create a new directive (called *directivename*) for a :term:`description
-     unit`.  It will automatically add index entries if *indextemplate* is
-     nonempty; if given, it must contain exactly one instance of ``%s``.  See
-     the example below for how the template will be interpreted.
+   * Create a new directive (called *directivename*) for documenting an object.
+     It will automatically add index entries if *indextemplate* is nonempty; if
+     given, it must contain exactly one instance of ``%s``.  See the example
+     below for how the template will be interpreted.
    * Create a new role (called *rolename*) to cross-reference to these
-     description units.
+     object descriptions.
    * If you provide *parse_node*, it must be a function that takes a string and
      a docutils node, and it must populate the node with children parsed from
      the string.  It must then return the name of the item to be used in
-     cross-referencing and index entries.  See the :file:`ext.py` file in the
+     cross-referencing and index entries.  See the :file:`conf.py` file in the
      source for this documentation for an example.
+   * The *objname* (if not given, will default to *directivename*) names the
+     type of object.  It is used when listing objects, e.g. in search results.
 
    For example, if you have this call in a custom Sphinx extension::
 
-      app.add_description_unit('directive', 'dir', 'pair: %s; directive')
+      app.add_object_type('directive', 'dir', 'pair: %s; directive')
 
    you can use this markup in your documents::
 
-      .. directive:: function
+      .. rst:directive:: function
 
          Document a function.
 
       <...>
 
-      See also the :dir:`function` directive.
+      See also the :rst:dir:`function` directive.
 
    For the directive, an index entry will be generated as if you had prepended ::
 
    ``docutils.nodes.emphasis`` or ``docutils.nodes.strong`` -- you can also use
    ``docutils.nodes.generated`` if you want no further text decoration).
 
-   For the role content, you have the same options as for standard Sphinx roles
-   (see :ref:`xref-syntax`).
+   For the role content, you have the same syntactical possibilities as for
+   standard Sphinx roles (see :ref:`xref-syntax`).
 
-.. method:: Sphinx.add_crossref_type(directivename, rolename, indextemplate='', ref_nodeclass=None)
+   This method is also available under the deprecated alias
+   :meth:`add_description_unit`.
 
-   This method is very similar to :meth:`add_description_unit` except that the
+.. method:: Sphinx.add_crossref_type(directivename, rolename, indextemplate='', ref_nodeclass=None, objname='')
+
+   This method is very similar to :meth:`add_object_type` except that the
    directive it generates must be empty, and will produce no output.
 
    That means that you can add semantic targets to your sources, and refer to
-   them using custom roles instead of generic ones (like :role:`ref`).  Example
+   them using custom roles instead of generic ones (like :rst:role:`ref`).  Example
    call::
 
       app.add_crossref_type('topic', 'topic', 'single: %s', docutils.nodes.emphasis)
 .. method:: Sphinx.emit_firstresult(event, *arguments)
 
    Emit *event* and pass *arguments* to the callback functions.  Return the
-   result of the first callback that doesn't return ``None`` (and don't call
-   the rest of the callbacks).
+   result of the first callback that doesn't return ``None``.
 
    .. versionadded:: 0.5
 
 
    .. versionadded:: 0.5
 
-.. event:: page-context (app, pagename, templatename, context, doctree)
+.. event:: html-collect-pages (app)
+
+   Emitted when the HTML builder is starting to write non-document pages.  You
+   can add pages to write by returning an iterable from this event consisting of
+   ``(pagename, context, templatename)``.
+
+   .. versionadded:: 1.0
+
+.. event:: html-page-context (app, pagename, templatename, context, doctree)
 
    Emitted when the HTML builder has created a context dictionary to render a
    template with -- this can be used to add custom elements to the context.
 
 .. autoclass:: TemplateBridge
    :members:
+
+
+.. _domain-api:
+
+Domain API
+----------
+
+.. module:: sphinx.domains
+
+.. autoclass:: Domain
+   :members:
+
+.. autoclass:: ObjType
+
+.. autoclass:: Index
+   :members:

doc/ext/autodoc.rst

 auto-generated-looking pure API documentation.
 
 :mod:`autodoc` provides several directives that are versions of the usual
-:dir:`module`, :dir:`class` and so forth.  On parsing time, they import the
+:rst:dir:`module`, :rst:dir:`class` and so forth.  On parsing time, they import the
 corresponding module and extract the docstring of the given objects, inserting
-them into the page source under a suitable :dir:`module`, :dir:`class` etc.
+them into the page source under a suitable :rst:dir:`module`, :rst:dir:`class` etc.
 directive.
 
 .. note::
 
-   Just as :dir:`class` respects the current :dir:`module`, :dir:`autoclass`
-   will also do so, and likewise with :dir:`method` and :dir:`class`.
+   Just as :rst:dir:`class` respects the current :rst:dir:`module`, :rst:dir:`autoclass`
+   will also do so, and likewise with :rst:dir:`method` and :rst:dir:`class`.
 
 
-.. directive:: automodule
+.. rst:directive:: automodule
                autoclass
                autoexception
 
         .. autoclass:: Noodle
            :members: eat, slurp
 
+   * If you want to make the ``members`` option the default, see
+     :confval:`autodoc_default_flags`.
+
    * Members without docstrings will be left out, unless you give the
      ``undoc-members`` flag option::
 
 
      .. versionadded:: 0.4
 
-   * The :dir:`automodule`, :dir:`autoclass` and :dir:`autoexception` directives
+   * The :rst:dir:`automodule`, :rst:dir:`autoclass` and :rst:dir:`autoexception` directives
      also support a flag option called ``show-inheritance``.  When given, a list
      of base classes will be inserted just below the class signature (when used
-     with :dir:`automodule`, this will be inserted for every class that is
+     with :rst:dir:`automodule`, this will be inserted for every class that is
      documented in the module).
 
      .. versionadded:: 0.4
 
    * All autodoc directives support the ``noindex`` flag option that has the
-     same effect as for standard :dir:`function` etc. directives: no index
+     same effect as for standard :rst:dir:`function` etc. directives: no index
      entries are generated for the documented object (and all autodocumented
      members).
 
      .. versionadded:: 0.4
 
-   * :dir:`automodule` also recognizes the ``synopsis``, ``platform`` and
-     ``deprecated`` options that the standard :dir:`module` directive supports.
+   * :rst:dir:`automodule` also recognizes the ``synopsis``, ``platform`` and
+     ``deprecated`` options that the standard :rst:dir:`module` directive supports.
 
      .. versionadded:: 0.5
 
-   * :dir:`automodule` and :dir:`autoclass` also has an ``member-order`` option
+   * :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.
 
 
    .. note::
 
-      In an :dir:`automodule` directive with the ``members`` option set, only
+      In an :rst:dir:`automodule` directive with the ``members`` option set, only
       module members whose ``__module__`` attribute is equal to the module name
       as given to ``automodule`` will be documented.  This is to prevent
       documentation of imported classes or functions.
 
 
-.. directive:: autofunction
+.. rst:directive:: autofunction
                autodata
                automethod
                autoattribute
 
-   These work exactly like :dir:`autoclass` etc., but do not offer the options
+   These work exactly like :rst:dir:`autoclass` etc., but do not offer the options
    used for automatic member documentation.
 
    For module data members and class attributes, documentation can either be put
           """Docstring for attribute Foo.baz."""
 
    .. versionchanged:: 0.6
-      :dir:`autodata` and :dir:`autoattribute` can now extract docstrings.
+      :rst:dir:`autodata` and :rst:dir:`autoattribute` can now extract docstrings.
 
    .. note::
 
 .. confval:: autoclass_content
 
    This value selects what content will be inserted into the main body of an
-   :dir:`autoclass` directive.  The possible values are:
+   :rst:dir:`autoclass` directive.  The possible values are:
 
    ``"class"``
       Only the class' docstring is inserted.  This is the default.  You can
-      still document ``__init__`` as a separate method using :dir:`automethod`
-      or the ``members`` option to :dir:`autoclass`.
+      still document ``__init__`` as a separate method using :rst:dir:`automethod`
+      or the ``members`` option to :rst:dir:`autoclass`.
    ``"both"``
       Both the class' and the ``__init__`` method's docstring are concatenated
       and inserted.
 .. confval:: autodoc_member_order