Commits

Zoom Quiet  committed e250e61

make doc-zh branch can build all Sphinx doc

  • Participants
  • Parent commits 20996e7
  • Branches doc-zh

Comments (0)

Files changed (19)

+Release 1.2 (in development)
+============================
+
+
+Release 1.1 (Oct 9, 2011)
+=========================
+
+Incompatible changes
+--------------------
+
+* 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.)
+
+* Removed support for old dependency versions; requirements are now:
+
+  - Pygments >= 1.2
+  - Docutils >= 0.7
+  - Jinja2   >= 2.3
+
+Features added
+--------------
+
+* Added Python 3.x support.
+
+* New builders and subsystems:
+
+  - Added a Texinfo builder.
+  - Added i18n support for content, a ``gettext`` builder and related
+    utilities.
+  - Added the ``websupport`` library and builder.
+  - #98: Added a ``sphinx-apidoc`` script that autogenerates a hierarchy
+    of source files containing autodoc directives to document modules
+    and packages.
+  - #273: Add an API for adding full-text search support for languages
+    other than English.  Add support for Japanese.
+
+* Markup:
+
+  - #138: Added an :rst:role:`index` role, to make inline index entries.
+  - #454: Added more index markup capabilities: marking see/seealso entries,
+    and main entries for a given key.
+  - #460: Allowed limiting the depth of section numbers for HTML using the
+    :rst:dir:`toctree`\'s ``numbered`` option.
+  - #586: Implemented improved :rst:dir:`glossary` markup which allows
+    multiple terms per definition.
+  - #478: Added :rst:dir:`py:decorator` directive to describe decorators.
+  - C++ domain now supports array definitions.
+  - C++ domain now supports doc fields (``:param x:`` inside directives).
+  - Section headings in :rst:dir:`only` directives are now correctly
+    handled.
+  - Added ``emphasize-lines`` option to source code directives.
+  - #678: C++ domain now supports superclasses.
+
+* HTML builder:
+
+  - Added ``pyramid`` theme.
+  - #559: :confval:`html_add_permalinks` is now a string giving the
+    text to display in permalinks.
+  - #259: HTML table rows now have even/odd CSS classes to enable
+    "Zebra styling".
+  - #554: Add theme option ``sidebarwidth`` to the basic theme.
+
+* Other builders:
+
+  - #516: Added new value of the :confval:`latex_show_urls` option to
+    show the URLs in footnotes.
+  - #209: Added :confval:`text_newlines` and :confval:`text_sectionchars`
+    config values.
+  - Added :confval:`man_show_urls` config value.
+  - #472: linkcheck builder: Check links in parallel, use HTTP HEAD
+    requests and allow configuring the timeout.  New config values:
+    :confval:`linkcheck_timeout` and :confval:`linkcheck_workers`.
+  - #521: Added :confval:`linkcheck_ignore` config value.
+  - #28: Support row/colspans in tables in the LaTeX builder.
+
+* Configuration and extensibility:
+
+  - #537: Added :confval:`nitpick_ignore`.
+  - #306: Added :event:`env-get-outdated` event.
+  - :meth:`.Application.add_stylesheet` now accepts full URIs.
+
+* Autodoc:
+
+  - #564: Add :confval:`autodoc_docstring_signature`.  When enabled (the
+    default), autodoc retrieves the signature from the first line of the
+    docstring, if it is found there.
+  - #176: Provide ``private-members`` option for autodoc directives.
+  - #520: Provide ``special-members`` option for autodoc directives.
+  - #431: Doc comments for attributes can now be given on the same line
+    as the assignment.
+  - #437: autodoc now shows values of class data attributes.
+  - autodoc now supports documenting the signatures of
+    ``functools.partial`` objects.
+
+* Other extensions:
+
+  - Added the :mod:`sphinx.ext.mathjax` extension.
+  - #443: Allow referencing external graphviz files.
+  - Added ``inline`` option to graphviz directives, and fixed the
+    default (block-style) in LaTeX output.
+  - #590: Added ``caption`` option to graphviz directives.
+  - #553: Added :rst:dir:`testcleanup` blocks in the doctest extension.
+  - #594: :confval:`trim_doctest_flags` now also removes ``<BLANKLINE>``
+    indicators.
+  - #367: Added automatic exclusion of hidden members in inheritance
+    diagrams, and an option to selectively enable it.
+  - Added :confval:`pngmath_add_tooltips`.
+  - The math extension displaymath directives now support ``name`` in
+    addition to ``label`` for giving the equation label, for compatibility
+    with Docutils.
+
+* New locales:
+
+  - #221: Added Swedish locale.
+  - #526: Added Iranian locale.
+  - #694: Added Latvian locale.
+  - Added Nepali locale.
+  - #714: Added Korean locale.
+  - #766: Added Estonian locale.
+
+
+Release 1.0.9 (in development)
+==============================
+
+* #778: Fix "hide search matches" link on pages linked by search.
+
+* Fix the source positions referenced by the "viewcode" extension.
+
+
+Release 1.0.8 (Sep 23, 2011)
+============================
+
+* #627: Fix tracebacks for AttributeErrors in autosummary generation.
+
+* Fix the ``abbr`` role when the abbreviation has newlines in it.
+
+* #727: Fix the links to search results with custom object types.
+
+* #648: Fix line numbers reported in warnings about undefined
+  references.
+
+* #696, #666: Fix C++ array definitions and template arguments
+  that are not type names.
+
+* #633: Allow footnotes in section headers in LaTeX output.
+
+* #616: Allow keywords to be linked via intersphinx.
+
+* #613: Allow Unicode characters in production list token names.
+
+* #720: Add dummy visitors for graphviz nodes for text and man.
+
+* #704: Fix image file duplication bug.
+
+* #677: Fix parsing of multiple signatures in C++ domain.
+
+* #637: Ignore Emacs lock files when looking for source files.
+
+* #544: Allow .pyw extension for importable modules in autodoc.
+
+* #700: Use ``$(MAKE)`` in quickstart-generated Makefiles.
+
+* #734: Make sidebar search box width consistent in browsers.
+
+* #644: Fix spacing of centered figures in HTML output.
+
+* #767: Safely encode SphinxError messages when printing them to
+  sys.stderr.
+
+* #611: Fix LaTeX output error with a document with no sections but
+  a link target.
+
+* Correctly treat built-in method descriptors as methods in autodoc.
+
+* #706: Stop monkeypatching the Python textwrap module.
+
+* #657: viewcode now works correctly with source files that have
+  non-ASCII encoding.
+
+* #669: Respect the ``noindex`` flag option in py:module directives.
+
+* #675: Fix IndexErrors when including nonexisting lines with
+  :rst:dir:`literalinclude`.
+
+* #676: Respect custom function/method parameter separator strings.
+
+* #682: Fix JS incompatibility with jQuery >= 1.5.
+
+* #693: Fix double encoding done when writing HTMLHelp .hhk files.
+
+* #647: Do not apply SmartyPants in parsed-literal blocks.
+
+* C++ domain now supports array definitions.
+
+
+Release 1.0.7 (Jan 15, 2011)
+============================
+
+* #347: Fix wrong generation of directives of static methods in
+  autosummary.
+
+* #599: Import PIL as ``from PIL import Image``.
+
+* #558: Fix longtables with captions in LaTeX output.
+
+* Make token references work as hyperlinks again in LaTeX output.
+
+* #572: Show warnings by default when reference labels cannot be
+  found.
+
+* #536: Include line number when complaining about missing reference
+  targets in nitpicky mode.
+
+* #590: Fix inline display of graphviz diagrams in LaTeX output.
+
+* #589: Build using app.build() in setup command.
+
+* Fix a bug in the inheritance diagram exception that caused base
+  classes to be skipped if one of them is a builtin.
+
+* Fix general index links for C++ domain objects.
+
+* #332: Make admonition boundaries in LaTeX output visible.
+
+* #573: Fix KeyErrors occurring on rebuild after removing a file.
+
+* Fix a traceback when removing files with globbed toctrees.
+
+* If an autodoc object cannot be imported, always re-read the
+  document containing the directive on next build.
+
+* If an autodoc object cannot be imported, show the full traceback
+  of the import error.
+
+* Fix a bug where the removal of download files and images wasn't
+  noticed.
+
+* #571: Implement ``~`` cross-reference prefix for the C domain.
+
+* Fix regression of LaTeX output with the fix of #556.
+
+* #568: Fix lookup of class attribute documentation on descriptors
+  so that comment documentation now works.
+
+* Fix traceback with ``only`` directives preceded by targets.
+
+* Fix tracebacks occurring for duplicate C++ domain objects.
+
+* Fix JavaScript domain links to objects with ``$`` in their name.
+
+
+Release 1.0.6 (Jan 04, 2011)
+============================
+
+* #581: Fix traceback in Python domain for empty cross-reference
+  targets.
+
+* #283: Fix literal block display issues on Chrome browsers.
+
+* #383, #148: Support sorting a limited range of accented characters
+  in the general index and the glossary.
+
+* #570: Try decoding ``-D`` and ``-A`` command-line arguments with
+  the locale's preferred encoding.
+
+* #528: Observe :confval:`locale_dirs` when looking for the JS
+  translations file.
+
+* #574: Add special code for better support of Japanese documents
+  in the LaTeX builder.
+
+* Regression of #77: If there is only one parameter given with
+  ``:param:`` markup, the bullet list is now suppressed again.
+
+* #556: Fix missing paragraph breaks in LaTeX output in certain
+  situations.
+
+* #567: Emit the ``autodoc-process-docstring`` event even for objects
+  without a docstring so that it can add content.
+
+* #565: In the LaTeX builder, not only literal blocks require different
+  table handling, but also quite a few other list-like block elements.
+
+* #515: Fix tracebacks in the viewcode extension for Python objects
+  that do not have a valid signature.
+
+* Fix strange reportings of line numbers for warnings generated from
+  autodoc-included docstrings, due to different behavior depending
+  on docutils version.
+
+* Several fixes to the C++ domain.
+
+
+Release 1.0.5 (Nov 12, 2010)
+============================
+
+* #557: Add CSS styles required by docutils 0.7 for aligned images
+  and figures.
+
+* In the Makefile generated by LaTeX output, do not delete pdf files
+  on clean; they might be required images.
+
+* #535: Fix LaTeX output generated for line blocks.
+
+* #544: Allow ``.pyw`` as a source file extension.
+
+
+Release 1.0.4 (Sep 17, 2010)
+============================
+
+* #524: Open intersphinx inventories in binary mode on Windows,
+  since version 2 contains zlib-compressed data.
+
+* #513: Allow giving non-local URIs for JavaScript files, e.g.
+  in the JSMath extension.
+
+* #512: Fix traceback when ``intersphinx_mapping`` is empty.
+
+
+Release 1.0.3 (Aug 23, 2010)
+============================
+
+* #495: Fix internal vs. external link distinction for links coming
+  from a docutils table-of-contents.
+
+* #494: Fix the ``maxdepth`` option for the ``toctree()`` template
+  callable when used with ``collapse=True``.
+
+* #507: Fix crash parsing Python argument lists containing brackets
+  in string literals.
+
+* #501: Fix regression when building LaTeX docs with figures that
+  don't have captions.
+
+* #510: Fix inheritance diagrams for classes that are not picklable.
+
+* #497: Introduce separate background color for the sidebar collapse
+  button, making it easier to see.
+
+* #502, #503, #496: Fix small layout bugs in several builtin themes.
+
+
+Release 1.0.2 (Aug 14, 2010)
+============================
+
+* #490: Fix cross-references to objects of types added by the
+  :func:`~.Sphinx.add_object_type` API function.
+
+* Fix handling of doc field types for different directive types.
+
+* Allow breaking long signatures, continuing with backlash-escaped
+  newlines.
+
+* Fix unwanted styling of C domain references (because of a namespace
+  clash with Pygments styles).
+
+* Allow references to PEPs and RFCs with explicit anchors.
+
+* #471: Fix LaTeX references to figures.
+
+* #482: When doing a non-exact search, match only the given type
+  of object.
+
+* #481: Apply non-exact search for Python reference targets with
+  ``.name`` for modules too.
+
+* #484: Fix crash when duplicating a parameter in an info field list.
+
+* #487: Fix setting the default role to one provided by the
+  ``oldcmarkup`` extension.
+
+* #488: Fix crash when json-py is installed, which provides a
+  ``json`` module but is incompatible to simplejson.
+
+* #480: Fix handling of target naming in intersphinx.
+
+* #486: Fix removal of ``!`` for all cross-reference roles.
+
+
+Release 1.0.1 (Jul 27, 2010)
+============================
+
+* #470: Fix generated target names for reST domain objects; they
+  are not in the same namespace.
+
+* #266: Add Bengali language.
+
+* #473: Fix a bug in parsing JavaScript object names.
+
+* #474: Fix building with SingleHTMLBuilder when there is no toctree.
+
+* Fix display names for objects linked to by intersphinx with
+  explicit targets.
+
+* Fix building with the JSON builder.
+
+* Fix hyperrefs in object descriptions for LaTeX.
+
+
+Release 1.0 (Jul 23, 2010)
+==========================
+
+Incompatible changes
+--------------------
+
+* 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.  A few builtin domains are
+  provided:
+
+  - Python
+  - C
+  - C++
+  - JavaScript
+  - reStructuredText
+
+* The old markup for defining and linking to C directives is now
+  deprecated.  It will not work anymore in future versions without
+  activating the :mod:`~sphinx.ext.oldcmarkup` extension; in Sphinx
+  1.0, it is activated by default.
+
+* Removed support for old dependency versions; requirements are now:
+
+  - docutils >= 0.5
+  - Jinja2   >= 2.2
+
+* Removed deprecated elements:
+
+  - ``exclude_dirs`` config value
+  - ``sphinx.builder`` module
+
+Features added
+--------------
+
+* General:
+
+  - Added a "nitpicky" mode that emits warnings for all missing
+    references.  It is activated by the :option:`-n` command-line switch
+    or the :confval:`nitpicky` config value.
+  - Added ``latexpdf`` target in quickstart Makefile.
+
+* Markup:
+
+  - The :rst:role:`menuselection` and :rst:role:`guilabel` roles now
+    support ampersand accelerators.
+  - New more compact doc field syntax is now recognized: ``:param type
+    name: description``.
+  - Added ``tab-width`` option to :rst:dir:`literalinclude` directive.
+  - Added ``titlesonly`` option to :rst:dir:`toctree` directive.
+  - Added the ``prepend`` and ``append`` options to the
+    :rst:dir:`literalinclude` directive.
+  - #284: All docinfo metadata is now put into the document metadata, not
+    just the author.
+  - The :rst:role:`ref` role can now also reference tables by caption.
+  - The :rst:dir:`include` directive now supports absolute paths, which
+    are interpreted as relative to the source directory.
+  - In the Python domain, references like ``:func:`.name``` now look for
+    matching names with any prefix if no direct match is found.
+
+* Configuration:
+
+  - Added :confval:`rst_prolog` config value.
+  - Added :confval:`html_secnumber_suffix` config value to control
+    section numbering format.
+  - Added :confval:`html_compact_lists` config value to control
+    docutils' compact lists feature.
+  - The :confval:`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
+    sidebar contents can be included only selectively.
+  - :confval:`html_static_path` can now contain single file entries.
+  - The new universal config value :confval:`exclude_patterns` makes the
+    old :confval:`unused_docs`, :confval:`exclude_trees` and
+    :confval:`exclude_dirnames` obsolete.
+  - Added :confval:`html_output_encoding` config value.
+  - Added the :confval:`latex_docclass` config value and made the
+    "twoside" documentclass option overridable by "oneside".
+  - Added the :confval:`trim_doctest_flags` config value, which is true
+    by default.
+  - Added :confval:`html_show_copyright` config value.
+  - Added :confval:`latex_show_pagerefs` and :confval:`latex_show_urls`
+    config values.
+  - The behavior of :confval:`html_file_suffix` changed slightly: the
+    empty string now means "no suffix" instead of "default suffix", use
+    ``None`` for "default suffix".
+
+* New builders:
+
+  - Added a builder for the Epub format.
+  - Added a builder for manual pages.
+  - Added a single-file HTML builder.
+
+* 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``.
+  - References now get the class ``internal`` if they are internal to
+    the whole project, as opposed to internal to the current page.
+  - External references can be styled differently with the new
+    ``externalrefs`` theme option for the default theme.
+  - In the default theme, the sidebar can experimentally now be made
+    collapsible using the new ``collapsiblesidebar`` theme option.
+  - #129: Toctrees are now wrapped in a ``div`` tag with class
+    ``toctree-wrapper`` in HTML output.
+  - The :data:`toctree` callable in templates now has a ``maxdepth``
+    keyword argument to control the depth of the generated tree.
+  - The :data:`toctree` callable in templates now accepts a
+    ``titles_only`` keyword argument.
+  - Added ``htmltitle`` block in layout template.
+  - In the JavaScript search, allow searching for object names including
+    the module name, like ``sys.argv``.
+  - Added new theme ``haiku``, inspired by the Haiku OS user guide.
+  - Added new theme ``nature``.
+  - Added new theme ``agogo``, created by Andi Albrecht.
+  - Added new theme ``scrolls``, created by Armin Ronacher.
+  - #193: Added a ``visitedlinkcolor`` theme option to the default
+    theme.
+  - #322: Improved responsiveness of the search page by loading the
+    search index asynchronously.
+
+* Extension API:
+
+  - Added :event:`html-collect-pages`.
+  - Added :confval:`needs_sphinx` config value and
+    :meth:`~sphinx.application.Sphinx.require_sphinx` application API
+    method.
+  - #200: Added :meth:`~sphinx.application.Sphinx.add_stylesheet`
+    application API method.
+
+* Extensions:
+
+  - Added the :mod:`~sphinx.ext.viewcode` extension.
+  - Added the :mod:`~sphinx.ext.extlinks` extension.
+  - Added support for source ordering of members in autodoc, with
+    ``autodoc_member_order = 'bysource'``.
+  - Added :confval:`autodoc_default_flags` config value, which can be
+    used to select default flags for all autodoc directives.
+  - Added a way for intersphinx to refer to named labels in other
+    projects, and to specify the project you want to link to.
+  - #280: Autodoc can now document instance attributes assigned in
+    ``__init__`` methods.
+  - Many improvements and fixes to the :mod:`~sphinx.ext.autosummary`
+    extension, thanks to Pauli Virtanen.
+  - #309: The :mod:`~sphinx.ext.graphviz` extension can now output SVG
+    instead of PNG images, controlled by the
+    :confval:`graphviz_output_format` config value.
+  - Added ``alt`` option to :rst:dir:`graphviz` extension directives.
+  - Added ``exclude`` argument to :func:`.autodoc.between`.
+
+* Translations:
+
+  - Added Croatian translation, thanks to Bojan Mihelač.
+  - Added Turkish translation, thanks to Firat Ozgul.
+  - Added Catalan translation, thanks to Pau Fernández.
+  - Added simplified Chinese translation.
+  - Added Danish translation, thanks to Hjorth Larsen.
+  - Added Lithuanian translation, thanks to Dalius Dobravolskas.
+
+* Bugs fixed:
+
+  - #445: Fix links to result pages when using the search function
+    of HTML built with the ``dirhtml`` builder.
+  - #444: In templates, properly re-escape values treated with the
+    "striptags" Jinja filter.
+
+
+Release 0.6.7 (Jun 05, 2010)
+============================
+
+* #440: Remove usage of a Python >= 2.5 API in the ``literalinclude``
+  directive.
+
+* Fix a bug that prevented some references being generated in the
+  LaTeX builder.
+
+* #428: Add some missing CSS styles for standard docutils classes.
+
+* #432: Fix UnicodeErrors while building LaTeX in translated locale.
+
+
+Release 0.6.6 (May 25, 2010)
+============================
+
+* Handle raw nodes in the ``text`` writer.
+
+* Fix a problem the Qt help project generated by the ``qthelp``
+  builder that would lead to no content being displayed in the Qt
+  Assistant.
+
+* #393: Fix the usage of Unicode characters in mathematic formulas
+  when using the ``pngmath`` extension.
+
+* #404: Make ``\and`` work properly in the author field of the
+  ``latex_documents`` setting.
+
+* #409: Make the ``highlight_language`` config value work properly
+  in the LaTeX builder.
+
+* #418: Allow relocation of the translation JavaScript files to
+  the system directory on Unix systems.
+
+* #414: Fix handling of Windows newlines in files included with
+  the ``literalinclude`` directive.
+
+* #377: Fix crash in linkcheck builder.
+
+* #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)
+============================
+
+* In autodoc, fix the omission of some module members explicitly
+  documented using documentation comments.
+
+* #345: Fix cropping of sidebar scroll bar with ``stickysidebar``
+  option of the default theme.
+
+* #341: Always generate UNIX newlines in the quickstart Makefile.
+
+* #338: Fix running with ``-C`` under Windows.
+
+* In autodoc, allow customizing the signature of an object where
+  the built-in mechanism fails.
+
+* #331: Fix output for enumerated lists with start values in LaTeX.
+
+* Make the ``start-after`` and ``end-before`` options to the
+  ``literalinclude`` directive work correctly if not used together.
+
+* #321: Fix link generation in the LaTeX builder.
+
+
+Release 0.6.4 (Jan 12, 2010)
+============================
+
+* Improve the handling of non-Unicode strings in the configuration.
+
+* #316: Catch OSErrors occurring when calling graphviz with
+  arguments it doesn't understand.
+
+* Restore compatibility with Pygments >= 1.2.
+
+* #295: Fix escaping of hyperref targets in LaTeX output.
+
+* #302: Fix links generated by the ``:doc:`` role for LaTeX output.
+
+* #286: collect todo nodes after the whole document has been read;
+  this allows placing substitution references in todo items.
+
+* #294: do not ignore an explicit ``today`` config value in a
+  LaTeX build.
+
+* The ``alt`` text of inheritance diagrams is now much cleaner.
+
+* Ignore images in section titles when generating link captions.
+
+* #310: support exception messages in the ``testoutput`` blocks of
+  the ``doctest`` extension.
+
+* #293: line blocks are styled properly in HTML output.
+
+* #285: make the ``locale_dirs`` config value work again.
+
+* #303: ``html_context`` values given on the command line via ``-A``
+  should not override other values given in conf.py.
+
+* Fix a bug preventing incremental rebuilds for the ``dirhtml``
+  builder.
+
+* #299: Fix the mangling of quotes in some literal blocks.
+
+* #292: Fix path to the search index for the ``dirhtml`` builder.
+
+* Fix a Jython compatibility issue: make the dependence on the
+  ``parser`` module optional.
+
+* #238: In autodoc, catch all errors that occur on module import,
+  not just ``ImportError``.
+
+* Fix the handling of non-data, but non-method descriptors in autodoc.
+
+* When copying file times, ignore OSErrors raised by ``os.utime()``.
+
+
+Release 0.6.3 (Sep 03, 2009)
+============================
+
+* Properly add C module filenames as dependencies in autodoc.
+
+* #253: Ignore graphviz directives without content instead of
+  raising an unhandled exception.
+
+* #241: Fix a crash building LaTeX output for documents that contain
+  a todolist directive.
+
+* #252: Make it easier to change the build dir in the Makefiles
+  generated by quickstart.
+
+* #220: Fix CSS so that displaymath really is centered.
+
+* #222: Allow the "Footnotes" header to be translated.
+
+* #225: Don't add whitespace in generated HTML after inline tags.
+
+* #227: Make ``literalinclude`` work when the document's path
+  name contains non-ASCII characters.
+
+* #229: Fix autodoc failures with members that raise errors
+  on ``getattr()``.
+
+* #205: When copying files, don't copy full stat info, only
+  modification times.
+
+* #232: Support non-ASCII metadata in Qt help builder.
+
+* Properly format bullet lists nested in definition lists for LaTeX.
+
+* Section titles are now allowed inside ``only`` directives.
+
+* #201: Make ``centered`` directive work in LaTeX output.
+
+* #206: Refuse to overwrite an existing master document in
+  sphinx-quickstart.
+
+* #208: Use MS-sanctioned locale settings, determined by the
+  ``language`` config option, in the HTML help builder.
+
+* #210: Fix nesting of HTML tags for displayed math from pngmath
+  extension.
+
+* #213: Fix centering of images in LaTeX output.
+
+* #211: Fix compatibility with docutils 0.5.
+
+
+Release 0.6.2 (Jun 16, 2009)
+============================
+
+* #130: Fix obscure IndexError in doctest extension.
+
+* #167: Make glossary sorting case-independent.
+
+* #196: Add a warning if an extension module doesn't have a
+  ``setup()`` function.
+
+* #158: Allow '..' in template names, and absolute template paths;
+  Jinja 2 by default disables both.
+
+* When highlighting Python code, ignore extra indentation before
+  trying to parse it as Python.
+
+* #191: Don't escape the tilde in URIs in LaTeX.
+
+* Don't consider contents of source comments for the search index.
+
+* Set the default encoding to ``utf-8-sig`` to handle files with a
+  UTF-8 BOM correctly.
+
+* #178: apply ``add_function_parentheses`` config value to C
+  functions as promised.
+
+* #173: Respect the docutils ``title`` directive.
+
+* #172: The ``obj`` role now links to modules as promised.
+
+* #19: Tables now can have a "longtable" class, in order to get
+  correctly broken into pages in LaTeX output.
+
+* Look for Sphinx message catalogs in the system default path before
+  trying ``sphinx/locale``.
+
+* Fix the search for methods via "classname.methodname".
+
+* #155: Fix Python 2.4 compatibility: exceptions are old-style
+  classes there.
+
+* #150: Fix display of the "sphinxdoc" theme on Internet Explorer
+  versions 6 and 7.
+
+* #146: Don't fail to generate LaTeX when the user has an active
+  ``.docutils`` configuration.
+
+* #29: Don't generate visible "-{-}" in option lists in LaTeX.
+
+* Fix cross-reference roles when put into substitutions.
+
+* Don't put image "alt" text into table-of-contents entries.
+
+* In the LaTeX writer, do not raise an exception on too many section
+  levels, just use the "subparagraph" level for all of them.
+
+* #145: Fix autodoc problem with automatic members that refuse to be
+  getattr()'d from their parent.
+
+* If specific filenames to build are given on the command line,
+  check that they are within the source directory.
+
+* Fix autodoc crash for objects without a ``__name__``.
+
+* Fix intersphinx for installations without urllib2.HTTPSHandler.
+
+* #134: Fix pending_xref leftover nodes when using the todolist
+  directive from the todo extension.
+
+
+Release 0.6.1 (Mar 26, 2009)
+============================
+
+* #135: Fix problems with LaTeX output and the graphviz extension.
+
+* #132: Include the autosummary "module" template in the distribution.
+
+
+Release 0.6 (Mar 24, 2009)
+==========================
+
+New features added
+------------------
+
+* Incompatible changes:
+
+  - Templating now requires the Jinja2 library, which is an enhanced
+    version of the old Jinja1 engine.  Since the syntax and semantic
+    is largely the same, very few fixes should be necessary in
+    custom templates.
+
+  - The "document" div tag has been moved out of the ``layout.html``
+    template's "document" block, because the closing tag was already
+    outside.  If you overwrite this block, you need to remove your
+    "document" div tag as well.
+
+  - The ``autodoc_skip_member`` event now also gets to decide
+    whether to skip members whose name starts with underscores.
+    Previously, these members were always automatically skipped.
+    Therefore, if you handle this event, add something like this
+    to your event handler to restore the old behavior::
+
+       if name.startswith('_'):
+           return True
+
+* Theming support, see the new section in the documentation.
+
+* Markup:
+
+  - Due to popular demand, added a ``:doc:`` role which directly
+    links to another document without the need of creating a
+    label to which a ``:ref:`` could link to.
+
+  - #4: Added a ``:download:`` role that marks a non-document file
+    for inclusion into the HTML output and links to it.
+
+  - Added an ``only`` directive that can selectively include text
+    based on enabled "tags".  Tags can be given on the command
+    line.  Also, the current builder output format (e.g. "html" or
+    "latex") is always a defined tag.
+
+  - #10: Added HTML section numbers, enabled by giving a
+    ``:numbered:`` flag to the ``toctree`` directive.
+
+  - #114: Added an ``abbr`` role to markup abbreviations and
+    acronyms.
+
+  - The ``literalinclude`` directive now supports several more
+    options, to include only parts of a file.
+
+  - The ``toctree`` directive now supports a ``:hidden:`` flag,
+    which will prevent links from being generated in place of
+    the directive -- this allows you to define your document
+    structure, but place the links yourself.
+
+  - #123: The ``glossary`` directive now supports a ``:sorted:``
+    flag that sorts glossary entries alphabetically.
+
+  - Paths to images, literal include files and download files
+    can now be absolute (like ``/images/foo.png``).  They are
+    treated as relative to the top source directory.
+
+  - #52: There is now a ``hlist`` directive, creating a compact
+    list by placing distributing items into multiple columns.
+
+  - #77: If a description environment with info field list only
+    contains one ``:param:`` entry, no bullet list is generated.
+
+  - #6: Don't generate redundant ``<ul>`` for top-level TOC tree
+    items, which leads to a visual separation of TOC entries.
+
+  - #23: Added a ``classmethod`` directive along with ``method``
+    and ``staticmethod``.
+
+  - Scaled images now get a link to the unscaled version.
+
+  - SVG images are now supported in HTML (via ``<object>`` and
+    ``<embed>`` tags).
+
+  - Added a ``toctree`` callable to the templates, and the ability
+    to include external links in toctrees. The 'collapse' keyword
+    argument indicates whether or not to only display subitems of
+    the current page.  (Defaults to True.)
+
+* Configuration:
+
+  - The new config value ``rst_epilog`` can contain reST that is
+    appended to each source file that is read.  This is the right
+    place for global substitutions.
+
+  - The new ``html_add_permalinks`` config value can be used to
+    switch off the generated "paragraph sign" permalinks for each
+    heading and definition environment.
+
+  - The new ``html_show_sourcelink`` config value can be used to
+    switch off the links to the reST sources in the sidebar.
+
+  - The default value for ``htmlhelp_basename`` is now the project
+    title, cleaned up as a filename.
+
+  - The new ``modindex_common_prefix`` config value can be used to
+    ignore certain package names for module index sorting.
+
+  - The new ``trim_footnote_reference_space`` config value mirrors
+    the docutils config value of the same name and removes the
+    space before a footnote reference that is necessary for reST
+    to recognize the reference.
+
+  - The new ``latex_additional_files`` config value can be used to
+    copy files (that Sphinx doesn't copy automatically, e.g. if they
+    are referenced in custom LaTeX added in ``latex_elements``) to
+    the build directory.
+
+* Builders:
+
+  - The HTML builder now stores a small file named ``.buildinfo`` in
+    its output directory.  It stores a hash of config values that
+    can be used to determine if a full rebuild needs to be done (e.g.
+    after changing ``html_theme``).
+
+  - New builder for Qt help collections, by Antonio Valentino.
+
+  - The new ``DirectoryHTMLBuilder`` (short name ``dirhtml``) creates
+    a separate directory for every page, and places the page there
+    in a file called ``index.html``.  Therefore, page URLs and links
+    don't need to contain ``.html``.
+
+  - The new ``html_link_suffix`` config value can be used to select
+    the suffix of generated links between HTML files.
+
+  - #96: The LaTeX builder now supports figures wrapped by text, when
+    using the ``figwidth`` option and right/left alignment.
+
+* New translations:
+
+  - Italian by Sandro Dentella.
+  - Ukrainian by Petro Sasnyk.
+  - Finnish by Jukka Inkeri.
+  - Russian by Alexander Smishlajev.
+
+* Extensions and API:
+
+  - New ``graphviz`` extension to embed graphviz graphs.
+
+  - New ``inheritance_diagram`` extension to embed... inheritance
+    diagrams!
+
+  - New ``autosummary`` extension that generates summaries of
+    modules and automatic documentation of modules.
+
+  - Autodoc now has a reusable Python API, which can be used to
+    create custom types of objects to auto-document (e.g. Zope
+    interfaces).  See also ``Sphinx.add_autodocumenter()``.
+
+  - Autodoc now handles documented attributes.
+
+  - Autodoc now handles inner classes and their methods.
+
+  - Autodoc can document classes as functions now if explicitly
+    marked with `autofunction`.
+
+  - Autodoc can now exclude single members from documentation
+    via the ``exclude-members`` option.
+
+  - Autodoc can now order members either alphabetically (like
+    previously) or by member type; configurable either with the
+    config value ``autodoc_member_order`` or a ``member-order``
+    option per directive.
+
+  - The function ``Sphinx.add_directive()`` now also supports
+    docutils 0.5-style directive classes.  If they inherit from
+    ``sphinx.util.compat.Directive``, they also work with
+    docutils 0.4.
+
+  - There is now a ``Sphinx.add_lexer()`` method to be able to use
+    custom Pygments lexers easily.
+
+  - There is now ``Sphinx.add_generic_role()`` to mirror the
+    docutils' own function.
+
+* Other changes:
+
+  - Config overrides for single dict keys can now be given on the
+    command line.
+
+  - There is now a ``doctest_global_setup`` config value that can
+    be used to give setup code for all doctests in the documentation.
+
+  - Source links in HTML are now generated with ``rel="nofollow"``.
+
+  - Quickstart can now generate a Windows ``make.bat`` file.
+
+  - #62: There is now a ``-w`` option for sphinx-build that writes
+    warnings to a file, in addition to stderr.
+
+  - There is now a ``-W`` option for sphinx-build that turns warnings
+    into errors.
+
+
+Release 0.5.2 (Mar 24, 2009)
+============================
+
+* Properly escape ``|`` in LaTeX output.
+
+* #71: If a decoding error occurs in source files, print a
+  warning and replace the characters by "?".
+
+* Fix a problem in the HTML search if the index takes too long
+  to load.
+
+* Don't output system messages while resolving, because they
+  would stay in the doctrees even if keep_warnings is false.
+
+* #82: Determine the correct path for dependencies noted by
+  docutils.  This fixes behavior where a source with dependent
+  files was always reported as changed.
+
+* Recognize toctree directives that are not on section toplevel,
+  but within block items, such as tables.
+
+* Use a new RFC base URL, since rfc.org seems down.
+
+* Fix a crash in the todolist directive when no todo items are
+  defined.
+
+* Don't call LaTeX or dvipng over and over again if it was not
+  found once, and use text-only latex as a substitute in that case.
+
+* Fix problems with footnotes in the LaTeX output.
+
+* Prevent double hyphens becoming en-dashes in literal code in
+  the LaTeX output.
+
+* Open literalinclude files in universal newline mode to allow
+  arbitrary newline conventions.
+
+* Actually make the ``-Q`` option work.
+
+* #86: Fix explicit document titles in toctrees.
+
+* #81: Write environment and search index in a manner that is safe
+  from exceptions that occur during dumping.
+
+* #80: Fix UnicodeErrors when a locale is set with setlocale().
+
+
+Release 0.5.1 (Dec 15, 2008)
+============================
+
+* #67: Output warnings about failed doctests in the doctest extension
+  even when running in quiet mode.
+
+* #72: In pngmath, make it possible to give a full path to LaTeX and
+  dvipng on Windows.  For that to work, the ``pngmath_latex`` and
+  ``pngmath_dvipng`` options are no longer split into command and
+  additional arguments; use ``pngmath_latex_args`` and
+  ``pngmath_dvipng_args`` to give additional arguments.
+
+* Don't crash on failing doctests with non-ASCII characters.
+
+* Don't crash on writing status messages and warnings containing
+  unencodable characters.
+
+* Warn if a doctest extension block doesn't contain any code.
+
+* Fix the handling of ``:param:`` and ``:type:`` doc fields when
+  they contain markup (especially cross-referencing roles).
+
+* #65: Fix storage of depth information for PNGs generated by the
+  pngmath extension.
+
+* Fix autodoc crash when automethod is used outside a class context.
+
+* #68: Fix LaTeX writer output for images with specified height.
+
+* #60: Fix wrong generated image path when including images in sources
+  in subdirectories.
+
+* Fix the JavaScript search when html_copy_source is off.
+
+* Fix an indentation problem in autodoc when documenting classes
+  with the option ``autoclass_content = "both"`` set.
+
+* Don't crash on empty index entries, only emit a warning.
+
+* Fix a typo in the search JavaScript code, leading to unusable
+  search function in some setups.
+
+
+Release 0.5 (Nov 23, 2008) -- Birthday release!
+===============================================
+
+New features added
+------------------
+
+* Markup features:
+
+  - Citations are now global: all citation defined in any file can be
+    referenced from any file.  Citations are collected in a bibliography
+    for LaTeX output.
+
+  - Footnotes are now properly handled in the LaTeX builder: they appear
+    at the location of the footnote reference in text, not at the end of
+    a section.  Thanks to Andrew McNamara for the initial patch.
+
+  - "System Message" warnings are now automatically removed from the
+    built documentation, and only written to stderr.  If you want the
+    old behavior, set the new config value ``keep_warnings`` to True.
+
+  - Glossary entries are now automatically added to the index.
+
+  - Figures with captions can now be referred to like section titles,
+    using the ``:ref:`` role without an explicit link text.
+
+  - Added ``cmember`` role for consistency.
+
+  - Lists enumerated by letters or roman numerals are now handled like in
+    standard reST.
+
+  - The ``seealso`` directive can now also be given arguments, as a short
+    form.
+
+  - You can now document several programs and their options with the
+    new ``program`` directive.
+
+* HTML output and templates:
+
+  - Incompatible change: The "root" relation link (top left in the
+    relbar) now points to the ``master_doc`` by default, no longer to a
+    document called "index".  The old behavior, while useful in some
+    situations, was somewhat unexpected.  Override the "rootrellink"
+    block in the template to customize where it refers to.
+
+  - The JavaScript search now searches for objects before searching in
+    the full text.
+
+  - TOC tree entries now have CSS classes that make it possible to
+    style them depending on their depth.
+
+  - Highlighted code blocks now have CSS classes that make it possible
+    to style them depending on their language.
+
+  - HTML ``<meta>`` tags via the docutils ``meta`` directive are now
+    supported.
+
+  - ``SerializingHTMLBuilder`` was added as new abstract builder that
+    can be subclassed to serialize build HTML in a specific format.  The
+    ``PickleHTMLBuilder`` is a concrete subclass of it that uses pickle
+    as serialization implementation.
+
+  - ``JSONHTMLBuilder`` was added as another ``SerializingHTMLBuilder``
+    subclass that dumps the generated HTML into JSON files for further
+    processing.
+
+  - The ``rellinks`` block in the layout template is now called
+    ``linktags`` to avoid confusion with the relbar links.
+
+  - The HTML builders have two additional attributes now that can be
+    used to disable the anchor-link creation after headlines and
+    definition links.
+
+  - Only generate a module index if there are some modules in the
+    documentation.
+
+* New and changed config values:
+
+  - Added support for internationalization in generated text with the
+    ``language`` and ``locale_dirs`` config values.  Many thanks to
+    language contributors:
+
+    * Horst Gutmann -- German
+    * Pavel Kosina -- Czech
+    * David Larlet -- French
+    * Michał Kandulski -- Polish
+    * Yasushi Masuda -- Japanese
+    * Guillem Borrell -- Spanish
+    * Luc Saffre and Peter Bertels -- Dutch
+    * Fred Lin -- Traditional Chinese
+    * Roger Demetrescu -- Brazilian Portuguese
+    * Rok Garbas -- Slovenian
+
+  - The new config value ``highlight_language`` set a global default for
+    highlighting.  When ``'python3'`` is selected, console output blocks
+    are recognized like for ``'python'``.
+
+  - Exposed Pygments' lexer guessing as a highlight "language" ``guess``.
+
+  - The new config value ``latex_elements`` allows to override all LaTeX
+    snippets that Sphinx puts into the generated .tex file by default.
+
+  - Added ``exclude_dirnames`` config value that can be used to exclude
+    e.g. CVS directories from source file search.
+
+  - Added ``source_encoding`` config value to select input encoding.
+
+* Extensions:
+
+  - The new extensions ``sphinx.ext.jsmath`` and ``sphinx.ext.pngmath``
+    provide math support for both HTML and LaTeX builders.
+
+  - The new extension ``sphinx.ext.intersphinx`` half-automatically
+    creates links to Sphinx documentation of Python objects in other
+    projects.
+
+  - The new extension ``sphinx.ext.todo`` allows the insertion of
+    "To do" directives whose visibility in the output can be toggled.
+    It also adds a directive to compile a list of all todo items.
+
+  - sphinx.ext.autodoc has a new event ``autodoc-process-signature``
+    that allows tuning function signature introspection.
+
+  - sphinx.ext.autodoc has a new event ``autodoc-skip-member`` that allows
+    tuning which members are included in the generated content.
+
+  - Respect __all__ when autodocumenting module members.
+
+  - The `automodule` directive now supports the ``synopsis``,
+    ``deprecated`` and ``platform`` options.
+
+* Extension API:
+
+  - ``Sphinx.add_node()`` now takes optional visitor methods for the
+    HTML, LaTeX and text translators; this prevents having to manually
+    patch the classes.
+
+  - Added ``Sphinx.add_javascript()`` that adds scripts to load in the
+    default HTML template.
+
+  - Added new events: ``source-read``, ``env-updated``,
+    ``env-purge-doc``, ``missing-reference``, ``build-finished``.
+
+* Other changes:
+
+  - Added a command-line switch ``-Q``: it will suppress warnings.
+
+  - Added a command-line switch ``-A``: it can be used to supply
+    additional values into the HTML templates.
+
+  - Added a command-line switch ``-C``: if it is given, no configuration
+    file ``conf.py`` is required.
+
+  - Added a distutils command `build_sphinx`: When Sphinx is installed,
+    you can call ``python setup.py build_sphinx`` for projects that have
+    Sphinx documentation, which will build the docs and place them in
+    the standard distutils build directory.
+
+  - In quickstart, if the selected root path already contains a Sphinx
+    project, complain and abort.
+
+Bugs fixed
+----------
+
+* #51: Escape configuration values placed in HTML templates.
+
+* #44: Fix small problems in HTML help index generation.
+
+* Fix LaTeX output for line blocks in tables.
+
+* #38: Fix "illegal unit" error when using pixel image widths/heights.
+
+* Support table captions in LaTeX output.
+
+* #39: Work around a bug in Jinja that caused "<generator ...>" to be
+  emitted in HTML output.
+
+* Fix a problem with module links not being generated in LaTeX output.
+
+* Fix the handling of images in different directories.
+
+* #29: Support option lists in the text writer.  Make sure that dashes
+  introducing long option names are not contracted to en-dashes.
+
+* Support the "scale" option for images in HTML output.
+
+* #25: Properly escape quotes in HTML help attribute values.
+
+* Fix LaTeX build for some description environments with ``:noindex:``.
+
+* #24: Don't crash on uncommon casing of role names (like ``:Class:``).
+
+* Only output ANSI colors on color terminals.
+
+* Update to newest fncychap.sty, to fix problems with non-ASCII
+  characters at the start of chapter titles.
+
+* Fix a problem with index generation in LaTeX output, caused by
+  hyperref not being included last.
+
+* Don't disregard return annotations for functions without any parameters.
+
+* Don't throw away labels for code blocks.
+
+
+Release 0.4.3 (Oct 8, 2008)
+===========================
+
+* Fix a bug in autodoc with directly given autodoc members.
+
+* Fix a bug in autodoc that would import a module twice, once as
+  "module", once as "module.".
+
+* Fix a bug in the HTML writer that created duplicate ``id``
+  attributes for section titles with docutils 0.5.
+
+* Properly call ``super()`` in overridden blocks in templates.
+
+* Add a fix when using XeTeX.
+
+* Unify handling of LaTeX escaping.
+
+* Rebuild everything when the ``extensions`` config value changes.
+
+* Don't try to remove a nonexisting static directory.
+
+* Fix an indentation problem in production lists.
+
+* Fix encoding handling for literal include files: ``literalinclude``
+  now has an ``encoding`` option that defaults to UTF-8.
+
+* Fix the handling of non-ASCII characters entered in quickstart.
+
+* Fix a crash with nonexisting image URIs.
+
+
+Release 0.4.2 (Jul 29, 2008)
+============================
+
+* Fix rendering of the ``samp`` role in HTML.
+
+* Fix a bug with LaTeX links to headings leading to a wrong page.
+
+* Reread documents with globbed toctrees when source files are
+  added or removed.
+
+* Add a missing parameter to PickleHTMLBuilder.handle_page().
+
+* Put inheritance info always on its own line.
+
+* Don't automatically enclose code with whitespace in it in quotes;
+  only do this for the ``samp`` role.
+
+* autodoc now emits a more precise error message when a module
+  can't be imported or an attribute can't be found.
+
+* The JavaScript search now uses the correct file name suffix when
+  referring to found items.
+
+* The automodule directive now accepts the ``inherited-members``
+  and ``show-inheritance`` options again.
+
+* You can now rebuild the docs normally after relocating the source
+  and/or doctree directory.
+
+
+Release 0.4.1 (Jul 5, 2008)
+===========================
+
+* Added sub-/superscript node handling to TextBuilder.
+
+* Label names in references are now case-insensitive, since reST
+  label names are always lowercased.
+
+* Fix linkcheck builder crash for malformed URLs.
+
+* Add compatibility for admonitions and docutils 0.5.
+
+* Remove the silly restriction on "rubric" in the LaTeX writer: you
+  can now write arbitrary "rubric" directives, and only those with
+  a title of "Footnotes" will be ignored.
+
+* Copy the HTML logo to the output ``_static`` directory.
+
+* Fix LaTeX code for modules with underscores in names and platforms.
+
+* Fix a crash with nonlocal image URIs.
+
+* Allow the usage of :noindex: in ``automodule`` directives, as
+  documented.
+
+* Fix the ``delete()`` docstring processor function in autodoc.
+
+* Fix warning message for nonexisting images.
+
+* Fix JavaScript search in Internet Explorer.
+
+
+Release 0.4 (Jun 23, 2008)
+==========================
+
+New features added
+------------------
+
+* ``tocdepth`` can be given as a file-wide metadata entry, and
+  specifies the maximum depth of a TOC of this file.
+
+* The new config value `default_role` can be used to select the
+  default role for all documents.
+
+* Sphinx now interprets field lists with fields like ``:param foo:``
+  in description units.
+
+* The new `staticmethod` directive can be used to mark methods as
+  static methods.
+
+* HTML output:
+
+  - The "previous" and "next" links have a more logical structure, so
+    that by following "next" links you can traverse the entire TOC
+    tree.
+
+  - The new event `html-page-context` can be used to include custom
+    values into the context used when rendering an HTML template.
+
+  - Document metadata is now in the default template context, under
+    the name `metadata`.
+
+  - The new config value `html_favicon` can be used to set a favicon
+    for the HTML output.  Thanks to Sebastian Wiesner.
+
+  - The new config value `html_use_index` can be used to switch index
+    generation in HTML documents off.
+
+  - The new config value `html_split_index` can be used to create
+    separate index pages for each letter, to be used when the complete
+    index is too large for one page.
+
+  - The new config value `html_short_title` can be used to set a
+    shorter title for the documentation which is then used in the
+    navigation bar.
+
+  - The new config value `html_show_sphinx` can be used to control
+    whether a link to Sphinx is added to the HTML footer.
+
+  - The new config value `html_file_suffix` can be used to set the
+    HTML file suffix to e.g. ``.xhtml``.
+
+  - The directories in the `html_static_path` can now contain
+    subdirectories.
+
+  - The module index now isn't collapsed if the number of submodules
+    is larger than the number of toplevel modules.
+
+* The image directive now supports specifying the extension as ``.*``,
+  which makes the builder select the one that matches best.  Thanks to
+  Sebastian Wiesner.
+
+* The new config value `exclude_trees` can be used to exclude whole
+  subtrees from the search for source files.
+
+* Defaults for configuration values can now be callables, which allows
+  dynamic defaults.
+
+* The new TextBuilder creates plain-text output.
+
+* Python 3-style signatures, giving a return annotation via ``->``,
+  are now supported.
+
+* Extensions:
+
+  - The autodoc extension now offers a much more flexible way to
+    manipulate docstrings before including them into the output, via
+    the new `autodoc-process-docstring` event.
+
+  - The `autodoc` extension accepts signatures for functions, methods
+    and classes now that override the signature got via introspection
+    from Python code.
+
+  - The `autodoc` extension now offers a ``show-inheritance`` option
+    for autoclass that inserts a list of bases after the signature.
+
+  - The autodoc directives now support the ``noindex`` flag option.
+
+
+Bugs fixed
+----------
+
+* Correctly report the source location for docstrings included with
+  autodoc.
+
+* Fix the LaTeX output of description units with multiple signatures.
+
+* Handle the figure directive in LaTeX output.
+
+* Handle raw admonitions in LaTeX output.
+
+* Fix determination of the title in HTML help output.
+
+* Handle project names containing spaces.
+
+* Don't write SSI-like comments in HTML output.
+
+* Rename the "sidebar" class to "sphinxsidebar" in order to stay different
+  from reST sidebars.
+
+* Use a binary TOC in HTML help generation to fix issues links without
+  explicit anchors.
+
+* Fix behavior of references to functions/methods with an explicit title.
+
+* Support citation, subscript and superscript nodes in LaTeX writer.
+
+* Provide the standard "class" directive as "cssclass"; else it is
+  shadowed by the Sphinx-defined directive.
+
+* Fix the handling of explicit module names given to autoclass directives.
+  They now show up with the correct module name in the generated docs.
+
+* Enable autodoc to process Unicode docstrings.
+
+* The LaTeX writer now translates line blocks with ``\raggedright``,
+  which plays nicer with tables.
+
+* Fix bug with directories in the HTML builder static path.
+
+
+Release 0.3 (May 6, 2008)
+=========================
+
+New features added
+------------------
+
+* The ``toctree`` directive now supports a ``glob`` option that allows
+  glob-style entries in the content.
+
+* If the `pygments_style` config value contains a dot it's treated as the
+  import path of a custom Pygments style class.
+
+* A new config value, `exclude_dirs`, can be used to exclude whole
+  directories from the search for source files.
+
+* The configuration directory (containing ``conf.py``) can now be set
+  independently from the source directory.  For that, a new command-line
+  option ``-c`` has been added.
+
+* A new directive ``tabularcolumns`` can be used to give a tabular column
+  specification for LaTeX output.  Tables now use the ``tabulary`` package.
+  Literal blocks can now be placed in tables, with several caveats.
+
+* A new config value, `latex_use_parts`, can be used to enable parts in LaTeX
+  documents.
+
+* Autodoc now skips inherited members for classes, unless you give the
+  new ``inherited-members`` option.
+
+* A new config value, `autoclass_content`, selects if the docstring of the
+  class' ``__init__`` method is added to the directive's body.
+
+* Support for C++ class names (in the style ``Class::Function``) in C function
+  descriptions.
+
+* Support for a ``toctree_only`` item in items for the ``latex_documents``
+  config value.  This only includes the documents referenced by TOC trees in the
+  output, not the rest of the file containing the directive.
+
+Bugs fixed
+----------
+
+* sphinx.htmlwriter: Correctly write the TOC file for any structure of the
+  master document.  Also encode non-ASCII characters as entities in TOC
+  and index file.  Remove two remaining instances of hard-coded
+  "documentation".
+
+* sphinx.ext.autodoc: descriptors are detected properly now.
+
+* sphinx.latexwriter: implement all reST admonitions, not just ``note``
+  and ``warning``.
+
+* Lots of little fixes to the LaTeX output and style.
+
+* Fix OpenSearch template and make template URL absolute.  The
+  `html_use_opensearch` config value now must give the base URL.
+
+* Some unused files are now stripped from the HTML help file build.
+
+
+Release 0.2 (Apr 27, 2008)
+==========================
+
+Incompatible changes
+--------------------
+
+* Jinja, the template engine used for the default HTML templates, is now
+  no longer shipped with Sphinx.  If it is not installed automatically for
+  you (it is now listed as a dependency in ``setup.py``), install it manually
+  from PyPI.  This will also be needed if you're using Sphinx from a SVN
+  checkout; in that case please also remove the ``sphinx/jinja`` directory
+  that may be left over from old revisions.
+
+* The clumsy handling of the ``index.html`` template was removed.  The config
+  value ``html_index`` is gone, and ``html_additional_pages`` should be used
+  instead.  If you need it, the old ``index.html`` template is still there,
+  called ``defindex.html``, and you can port your html_index template, using
+  Jinja inheritance, by changing your template::
+
+     {% extends "defindex.html" %}
+     {% block tables %}
+     ... old html_index template content ...
+     {% endblock %}
+
+  and putting ``'index': name of your template`` in ``html_additional_pages``.
+
+* In the layout template, redundant ``block``\s were removed; you should use
+  Jinja's standard ``{{ super() }}`` mechanism instead, as explained in the
+  (newly written) templating docs.
+
+New features added
+------------------
+
+* Extension API (Application object):
+
+  - Support a new method, ``add_crossref_type``.  It works like
+    ``add_description_unit`` but the directive will only create a target
+    and no output.
+  - Support a new method, ``add_transform``.  It takes a standard docutils
+    ``Transform`` subclass which is then applied by Sphinx' reader on
+    parsing reST document trees.
+  - Add support for other template engines than Jinja, by adding an
+    abstraction called a "template bridge".  This class handles rendering
+    of templates and can be changed using the new configuration value
+    "template_bridge".
+  - The config file itself can be an extension (if it provides a ``setup()``
+    function).
+
+* Markup:
+
+  - New directive, ``currentmodule``.  It can be used to indicate the module
+    name of the following documented things without creating index entries.
+  - Allow giving a different title to documents in the toctree.
+  - Allow giving multiple options in a ``cmdoption`` directive.
+  - Fix display of class members without explicit class name given.
+
+* Templates (HTML output):
+
+  - ``index.html`` renamed to ``defindex.html``, see above.
+  - There's a new config value, ``html_title``, that controls the overall
+    "title" of the set of Sphinx docs.  It is used instead everywhere instead of
+    "Projectname vX.Y documentation" now.
+  - All references to "documentation" in the templates have been removed, so
+    that it is now easier to use Sphinx for non-documentation documents with
+    the default templates.
+  - Templates now have an XHTML doctype, to be consistent with docutils'
+    HTML output.
+  - You can now create an OpenSearch description file with the
+    ``html_use_opensearch`` config value.
+  - You can now quickly include a logo in the sidebar, using the ``html_logo``
+    config value.
+  - There are new blocks in the sidebar, so that you can easily insert content
+    into the sidebar.
+
+* LaTeX output:
+
+  - The ``sphinx.sty`` package was cleaned of unused stuff.
+  - You can include a logo in the title page with the ``latex_logo`` config
+    value.
+  - You can define the link colors and a border and background color for
+    verbatim environments.
+
+Thanks to Jacob Kaplan-Moss, Talin, Jeroen Ruigrok van der Werven and Sebastian
+Wiesner for suggestions.
+
+Bugs fixed
+----------
+
+* sphinx.ext.autodoc: Don't check ``__module__`` for explicitly given
+  members.  Remove "self" in class constructor argument list.
+
+* sphinx.htmlwriter: Don't use os.path for joining image HREFs.
+
+* sphinx.htmlwriter: Don't use SmartyPants for HTML attribute values.
+
+* sphinx.latexwriter: Implement option lists.  Also, some other changes
+  were made to ``sphinx.sty`` in order to enhance compatibility and
+  remove old unused stuff.  Thanks to Gael Varoquaux for that!
+
+* sphinx.roles: Fix referencing glossary terms with explicit targets.
+
+* sphinx.environment: Don't swallow TOC entries when resolving subtrees.
+
+* sphinx.quickstart: Create a sensible default latex_documents setting.
+
+* sphinx.builder, sphinx.environment: Gracefully handle some user error
+  cases.
+
+* sphinx.util: Follow symbolic links when searching for documents.
+
+
+Release 0.1.61950 (Mar 26, 2008)
+================================
+
+* sphinx.quickstart: Fix format string for Makefile.
+
+
+Release 0.1.61945 (Mar 26, 2008)
+================================
+
+* sphinx.htmlwriter, sphinx.latexwriter: Support the ``.. image::``
+  directive by copying image files to the output directory.
+
+* sphinx.builder: Consistently name "special" HTML output directories
+  with a leading underscore; this means ``_sources`` and ``_static``.
+
+* sphinx.environment: Take dependent files into account when collecting
+  the set of outdated sources.
+
+* sphinx.directives: Record files included with ``.. literalinclude::``
+  as dependencies.
+
+* sphinx.ext.autodoc: Record files from which docstrings are included
+  as dependencies.
+
+* sphinx.builder: Rebuild all HTML files in case of a template change.
+
+* sphinx.builder: Handle unavailability of TOC relations (previous/
+  next chapter) more gracefully in the HTML builder.
+
+* sphinx.latexwriter: Include fncychap.sty which doesn't seem to be
+  very common in TeX distributions.  Add a ``clean`` target in the
+  latex Makefile.  Really pass the correct paper and size options
+  to the LaTeX document class.
+
+* setup: On Python 2.4, don't egg-depend on docutils if a docutils is
+  already installed -- else it will be overwritten.
+
+
+Release 0.1.61843 (Mar 24, 2008)
+================================
+
+* sphinx.quickstart: Really don't create a makefile if the user
+  doesn't want one.
+
+* setup: Don't install scripts twice, via setuptools entry points
+  and distutils scripts.  Only install via entry points.
+
+* sphinx.builder: Don't recognize the HTML builder's copied source
+  files (under ``_sources``) as input files if the source suffix is
+  ``.txt``.
+
+* sphinx.highlighting: Generate correct markup for LaTeX Verbatim
+  environment escapes even if Pygments is not installed.
+
+* sphinx.builder: The WebHTMLBuilder is now called PickleHTMLBuilder.
+
+* sphinx.htmlwriter: Make parsed-literal blocks work as expected,
+  not highlighting them via Pygments.
+
+* sphinx.environment: Don't error out on reading an empty source file.
+
+
+Release 0.1.61798 (Mar 23, 2008)
+================================
+
+* sphinx: Work with docutils SVN snapshots as well as 0.4.
+
+* sphinx.ext.doctest: Make the group in which doctest blocks are
+  placed selectable, and default to ``'default'``.
+
+* sphinx.ext.doctest: Replace ``<BLANKLINE>`` in doctest blocks by
+  real blank lines for presentation output, and remove doctest
+  options given inline.
+
+* sphinx.environment: Move doctest_blocks out of block_quotes to
+  support indented doctest blocks.
+
+* sphinx.ext.autodoc: Render ``.. automodule::`` docstrings in a
+  section node, so that module docstrings can contain proper
+  sectioning.
+
+* sphinx.ext.autodoc: Use the module's encoding for decoding
+  docstrings, rather than requiring ASCII.
+
+
+Release 0.1.61611 (Mar 21, 2008)
+================================
+
+* First public release.
+Projects using Sphinx
+=====================
+
+This is an (incomplete) alphabetic list of projects that use Sphinx or
+are experimenting with using it for their documentation.  If you like to
+be included, please mail to `the Google group
+<http://groups.google.com/group/sphinx-dev>`_.
+
+I've grouped the list into sections to make it easier to find
+interesting examples.
+
+Documentation using the default theme
+-------------------------------------
+
+* APSW: http://apidoc.apsw.googlecode.com/hg/index.html
+* ASE: https://wiki.fysik.dtu.dk/ase/
+* boostmpi: http://documen.tician.de/boostmpi/
+* Calibre: http://calibre-ebook.com/user_manual/
+* CodePy: http://documen.tician.de/codepy/
+* Cython: http://docs.cython.org/
+* C\\C++ Python language binding project: http://language-binding.net/index.html
+* Cormoran: http://cormoran.nhopkg.org/docs/
+* Director: http://packages.python.org/director/
+* Dirigible: http://www.projectdirigible.com/documentation/
+* Elemental: http://elemental.googlecode.com/hg/doc/build/html/index.html
+* F2py: http://f2py.sourceforge.net/docs/
+* GeoDjango: http://geodjango.org/docs/
+* Genomedata: http://noble.gs.washington.edu/proj/genomedata/doc/1.2.2/genomedata.html
+* gevent: http://www.gevent.org/
+* Google Wave API: http://wave-robot-python-client.googlecode.com/svn/trunk/pydocs/index.html
+* GSL Shell: http://www.nongnu.org/gsl-shell/
+* Heapkeeper: http://heapkeeper.org/
+* Hands-on Python Tutorial: http://anh.cs.luc.edu/python/hands-on/3.1/handsonHtml/
+* Hedge: http://documen.tician.de/hedge/
+* Kaa: http://doc.freevo.org/api/kaa/
+* Leo: http://webpages.charter.net/edreamleo/front.html
+* Lino: http://lino.saffre-rumma.net/
+* MeshPy: http://documen.tician.de/meshpy/
+* mpmath: http://mpmath.googlecode.com/svn/trunk/doc/build/index.html
+* OpenEXR: http://excamera.com/articles/26/doc/index.html
+* OpenGDA: http://www.opengda.org/gdadoc/html/
+* openWNS: http://docs.openwns.org/
+* Paste: http://pythonpaste.org/script/
+* Paver: http://paver.github.com/paver/
+* Pyccuracy: https://github.com/heynemann/pyccuracy/wiki/
+* PyCuda: http://documen.tician.de/pycuda/
+* Pyevolve: http://pyevolve.sourceforge.net/
+* Pylo: http://documen.tician.de/pylo/
+* PyMQI: http://packages.python.org/pymqi/
+* PyPubSub: http://pubsub.sourceforge.net/
+* pyrticle: http://documen.tician.de/pyrticle/
+* Python: http://docs.python.org/
+* python-apt: http://apt.alioth.debian.org/python-apt-doc/
+* PyUblas: http://documen.tician.de/pyublas/
+* Quex: http://quex.sourceforge.net/doc/html/main.html
+* Scapy: http://www.secdev.org/projects/scapy/doc/
+* Segway: http://noble.gs.washington.edu/proj/segway/doc/1.1.0/segway.html
+* SimPy: http://simpy.sourceforge.net/SimPyDocs/index.html
+* SymPy: http://docs.sympy.org/
+* WTForms: http://wtforms.simplecodes.com/docs/
+* z3c: http://docs.carduner.net/z3c-tutorial/
+
+
+Documentation using a customized version of the default theme
+-------------------------------------------------------------
+
+* Advanced Generic Widgets:
+  http://xoomer.virgilio.it/infinity77/AGW_Docs/index.html
+* 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
+* LEPL: http://www.acooke.org/lepl/
+* Mayavi: http://code.enthought.com/projects/mayavi/docs/development/html/mayavi
+* NOC: http://redmine.nocproject.org/projects/noc
+* NumPy: http://docs.scipy.org/doc/numpy/reference/
+* Peach^3: http://peach3.nl/doc/latest/userdoc/
+* PyLit: http://pylit.berlios.de/
+* Sage: http://sagemath.org/doc/
+* SciPy: http://docs.scipy.org/doc/scipy/reference/
+* simuPOP: http://simupop.sourceforge.net/manual_release/build/userGuide.html
+* Sprox: http://sprox.org/
+* TurboGears: http://turbogears.org/2.0/docs/
+* Zentyal: http://doc.zentyal.org/
+* Zope: http://docs.zope.org/zope2/index.html
+* zc.async: http://packages.python.org/zc.async/1.5.0/
+
+
+Documentation using the sphinxdoc theme
+---------------------------------------
+
+* Fityk: http://fityk.nieto.pl/
+* MapServer: http://mapserver.org/
+* Matplotlib: http://matplotlib.sourceforge.net/
+* Music21: http://mit.edu/music21/doc/html/contents.html
+* MyHDL: http://www.myhdl.org/doc/0.6/
+* NetworkX: http://networkx.lanl.gov/
+* Pweave: http://mpastell.com/pweave/
+* Pyre: http://docs.danse.us/pyre/sphinx/
+* Pysparse: http://pysparse.sourceforge.net/
+* PyTango:
+  http://www.tango-controls.org/static/PyTango/latest/doc/html/index.html
+* Reteisi: http://www.reteisi.org/contents.html
+* Satchmo: http://www.satchmoproject.com/docs/dev/
+* Sphinx: http://sphinx.pocoo.org/
+* Sqlkit: http://sqlkit.argolinux.org/
+* Tau: http://www.tango-controls.org/static/tau/latest/doc/html/index.html
+* Total Open Station: http://tops.berlios.de/
+* WebFaction: http://docs.webfaction.com/
+
+
+Documentation using another builtin theme
+-----------------------------------------
+
+* C/C++ Development with Eclipse: http://eclipsebook.in/ (agogo)
+* Distribute: http://packages.python.org/distribute/ (nature)
+* Jinja: http://jinja.pocoo.org/ (scrolls)
+* jsFiddle: http://doc.jsfiddle.net/ (nature)
+* pip: http://pip.openplans.org/ (nature)
+* Programmieren mit PyGTK und Glade (German):
+  http://www.florian-diesch.de/doc/python-und-glade/online/ (agogo)
+* Spring Python: http://springpython.webfactional.com/current/sphinx/index.html
+  (nature)
+* sqlparse: http://python-sqlparse.googlecode.com/svn/docs/api/index.html
+  (agogo)
+* Sylli: http://sylli.sourceforge.net/ (nature)
+* libLAS: http://liblas.org/ (nature)
+
+
+Documentation using a custom theme/integrated in a site
+-------------------------------------------------------
+
+* Blender: http://www.blender.org/documentation/250PythonDoc/
+* Blinker: http://discorporate.us/projects/Blinker/docs/
+* Classy: classy: http://classy.pocoo.org/
+* Django: http://docs.djangoproject.com/
+* e-cidadania: http://e-cidadania.readthedocs.org/en/latest/
+* Flask: http://flask.pocoo.org/docs/
+* Flask-OpenID: http://packages.python.org/Flask-OpenID/
+* Gameduino: http://excamera.com/sphinx/gameduino/
+* GeoServer: http://docs.geoserver.org/
+* Glashammer: http://glashammer.org/
+* MirrorBrain: http://mirrorbrain.org/docs/
+* nose: http://somethingaboutorange.com/mrl/projects/nose/
+* ObjectListView: http://objectlistview.sourceforge.net/python
+* Open ERP: http://doc.openerp.com/
+* OpenLayers: http://docs.openlayers.org/
+* PyEphem: http://rhodesmill.org/pyephem/
+* German Plone 4.0 user manual: http://www.hasecke.com/plone-benutzerhandbuch/4.0/
+* Pylons: http://pylonshq.com/docs/en/0.9.7/
+* PyMOTW: http://www.doughellmann.com/PyMOTW/
+* pypol: http://pypol.altervista.org/ (celery)
+* qooxdoo: http://manual.qooxdoo.org/current
+* Roundup: http://www.roundup-tracker.org/
+* Selenium: http://seleniumhq.org/docs/
+* Self: http://selflanguage.org/
+* Tablib: http://tablib.org/
+* SQLAlchemy: http://www.sqlalchemy.org/docs/
+* tinyTiM: http://tinytim.sourceforge.net/docs/2.0/
+* tipfy: http://www.tipfy.org/docs/
+* Werkzeug: http://werkzeug.pocoo.org/docs/
+* WFront: http://discorporate.us/projects/WFront/
+
+
+Homepages and other non-documentation sites
+-------------------------------------------
+
+* Applied Mathematics at the Stellenbosch University: http://dip.sun.ac.za/
+* A personal page: http://www.dehlia.in/
+* Benoit Boissinot: http://bboissin.appspot.com/
+* lunarsite: http://lunaryorn.de/
+* Red Hot Chili Python: http://redhotchilipython.com/
+* The Wine Cellar Book: http://www.thewinecellarbook.com/doc/en/
+* VOR: http://www.vor-cycling.be/
+
+
+Books produced using Sphinx
+---------------------------
+
+* "The ``repoze.bfg`` Web Application Framework":
+  http://www.amazon.com/repoze-bfg-Web-Application-Framework-Version/dp/0615345379
+* A Theoretical Physics Reference book: http://theoretical-physics.net/
+* "Simple and Steady Way of Learning for Software Engineering" (in Japanese):
+  http://www.amazon.co.jp/dp/477414259X/
+* "Expert Python Programming" (Japanese translation):
+  http://www.amazon.co.jp/dp/4048686291/
+* "Pomodoro Technique Illustrated" (Japanese translation):
+  http://www.amazon.co.jp/dp/4048689525/
+
 
 # You can set these variables from the command line.
 SPHINXOPTS   =
-SPHINXBUILD  = python ../sphinx-build.py
+#SPHINXBUILD  = python ../sphinx-build.py
+SPHINXBUILD  = python sphinx-build.py
 PAPER        =
 
 PAPEROPT_a4      = -D latex_paper_size=a4
+.. -*- restructuredtext -*-
+
+=================
+README for Sphinx
+=================
+
+Installing
+==========
+
+Use ``setup.py``::
+
+   python setup.py build
+   sudo python setup.py install
+
+
+Reading the docs
+================
+
+After installing::
+
+   cd doc
+   sphinx-build . _build/html
+
+Then, direct your browser to ``_build/html/index.html``.
+
+Or read them online at <http://sphinx.pocoo.org/>.
+
+
+Testing
+=======
+
+To run the tests with the interpreter available as ``python``, use::
+
+    make test
+
+If you want to use a different interpreter, e.g. ``python3``, use::
+
+    PYTHON=python3 make test
+
+
+Contributing
+============
+
+Send wishes, comments, patches, etc. to sphinx-dev@googlegroups.com.
+# -*- coding: utf-8 -*-
+"""
+    Sphinx
+    ~~~~~~
+
+    The Sphinx documentation toolchain.
+
+    :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS.
+    :license: BSD, see LICENSE for details.
+"""
+
+# Keep this file executable as-is in Python 3!
+# (Otherwise getting the version out of it from setup.py is impossible.)
+
+import sys
+from os import path
+
+__version__  = '1.2pre'
+__released__ = '1.2 (hg)'  # used when Sphinx builds its own docs
+
+package_dir = path.abspath(path.dirname(__file__))
+
+if '+' in __version__ or 'pre' in __version__:
+    # try to find out the changeset hash if checked out from hg, and append
+    # it to __version__ (since we use this value from setup.py, it gets
+    # automatically propagated to an installed copy as well)
+    try:
+        import subprocess
+        p = subprocess.Popen(['hg', 'id', '-i', '-R',
+                              path.join(package_dir, '..')],
+                             stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+        out, err = p.communicate()
+        if out:
+            __version__ += '/' + out.strip()
+    except Exception:
+        pass
+
+
+def main(argv=sys.argv):
+    """Sphinx build "main" command-line entry."""
+    if sys.version_info[:3] < (2, 4, 0):
+        sys.stderr.write('Error: Sphinx requires at least '
+                         'Python 2.4 to run.\n')
+        return 1
+
+    try:
+        from sphinx import cmdline
+    except ImportError:
+        err = sys.exc_info()[1]
+        errstr = str(err)
+        if errstr.lower().startswith('no module named'):
+            whichmod = errstr[16:]
+            hint = ''
+            if whichmod.startswith('docutils'):
+                whichmod = 'Docutils library'
+            elif whichmod.startswith('jinja'):
+                whichmod = 'Jinja2 library'
+            elif whichmod == 'roman':
+                whichmod = 'roman module (which is distributed with Docutils)'
+                hint = ('This can happen if you upgraded docutils using\n'
+                        'easy_install without uninstalling the old version'
+                        'first.\n')
+            else:
+                whichmod += ' module'
+            sys.stderr.write('Error: The %s cannot be found. '
+                             'Did you install Sphinx and its dependencies '
+                             'correctly?\n' % whichmod)
+            if hint:
+                sys.stderr.write(hint)
+            return 1
+        raise
+    return cmdline.main(argv)
+
+
+if __name__ == '__main__':
+    sys.exit(main(sys.argv))
 Changes in Sphinx
 *****************
 
-.. include:: ../CHANGES
+.. include:: CHANGES

File examples.rst

 
 .. _examples:
 
-.. include:: ../EXAMPLES
+.. include:: EXAMPLES

File sphinx-build.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 import main
+    sys.exit(main(sys.argv))

File web/storagebackends.rst

 .. automethod:: StorageBackend.accept_comment
 
 .. automethod:: StorageBackend.reject_comment
+

File websupport/__init__.py

+# -*- coding: utf-8 -*-
+"""
+    sphinx.websupport
+    ~~~~~~~~~~~~~~~~~
+
+    Base Module for web support functions.
+
+    :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS.
+    :license: BSD, see LICENSE for details.
+"""
+
+import cgi
+import sys
+import cPickle as pickle
+import posixpath
+from os import path
+
+from jinja2 import Environment, FileSystemLoader
+
+from docutils.core import publish_parts
+
+from sphinx.application import Sphinx
+from sphinx.util.osutil import ensuredir
+from sphinx.util.jsonimpl import dumps as dump_json
+from sphinx.websupport import errors
+from sphinx.websupport.search import BaseSearch, SEARCH_ADAPTERS
+from sphinx.websupport.storage import StorageBackend
+
+
+class WebSupport(object):
+    """The main API class for the web support package. All interactions
+    with the web support package should occur through this class.
+    """
+    def __init__(self,
+                 srcdir=None,     # only required for building
+                 builddir='',     # the dir with data/static/doctrees subdirs
+                 datadir=None,    # defaults to builddir/data
+                 staticdir=None,  # defaults to builddir/static
+                 doctreedir=None, # defaults to builddir/doctrees
+                 search=None,     # defaults to no search
+                 storage=None,    # defaults to SQLite in datadir
+                 status=sys.stdout,
+                 warning=sys.stderr,
+                 moderation_callback=None,
+                 allow_anonymous_comments=True,
+                 docroot='',
+                 staticroot='static',
+                 ):
+        # directories
+        self.srcdir = srcdir
+        self.builddir = builddir
+        self.outdir = path.join(builddir, 'data')