Anonymous avatar Anonymous committed da6503f Merge

Merge with birkenfeld/sphinx

Comments (0)

Files changed (196)

 e753d03451a6eddc1ad3876bd383a12c50aa4cf2 1.1.1
 7d389fe78ee953f32dcece8ef39b1f7136666f6a 1.1.2
 db20c81e10dc89d70fb3e6a841fd1760c350e725 1.1.3
+82674d950698806a785db6bf3b413d8266756767 1.2b1
-Release 1.2 (in development)
-============================
+Release 1.2 (beta1 released Mar 31, 2013)
+=========================================
 
-* PR#123, #1106: Add epub_use_index configuration value.
-  If provided, it will be used instead of html_use_index for epub builder.
+Incompatible changes
+--------------------
 
-* #1111: Fix uppercase word is not found in search when
-  html_search_language='ja'. Thanks to tomo saito.
+* Removed ``sphinx.util.compat.directive_dwim()`` and
+  ``sphinx.roles.xfileref_role()`` which were deprecated since version 1.0.
+* PR#122: the files given in :confval:`latex_additional_files` now override TeX
+  files included by Sphinx, such as ``sphinx.sty``.
+* PR#124: the node generated by :rst:dir:`versionadded`,
+  :rst:dir:`versionchanged` and :rst:dir:`deprecated` directives now includes
+  all added markup (such as "New in version X") as child nodes, and no
+  additional text must be generated by writers.
+* PR#99: the :rst:dir:`seealso` directive now generates admonition nodes instead
+  of the custom ``seealso`` node.
 
-* The ``'fontpkg'`` item in :confval:`latex_elements` now defaults to ``''``
-  when the :confval:`language` uses the Cyrillic script.
-  Suggested by Dmitry Shachnev.
+Features added
+--------------
 
-* PR#114: The LaTeX writer now includes the "cmap" package by default. The
-  ``'cmappkg'`` item in :confval:`latex_elements` can be used to control this.
-  Thanks to Dmitry Shachnev.
+* Markup
 
-* New locales: #1113: Added Hebrew locale.
+  - The :rst:dir:`toctree` directive and the ``toctree()`` template function now
+    have an ``includehidden`` option that includes hidden toctree entries (bugs
+    #790 and #1047).  A bug in the ``maxdepth`` option for the ``toctree()``
+    template function has been fixed (bug #1046).
+  - PR#99: Strip down seealso directives to normal admonitions.  This removes
+    their unusual CSS classes (admonition-see-also), inconsistent LaTeX
+    admonition title ("See Also" instead of "See also"), and spurious indentation
+    in the text builder.
 
-* PR#115: Add ``'transition'`` item in :confval:`latex_elements` for
-  customizing how transitions are displayed. Thanks to Jeff Klukas.
+* HTML builder
 
-* #1108: The text writer now correctly numbers enumerated lists with
-  non-default start values (based on patch by Ewan Edwards).
-
-* #1074: Add environment version info to the generated search index to avoid
-  compatibility issues with old builds.
-
-* New locales: #1097: Added Basque locale.
-
-* Fix text builder did not respect wide/fullwidth characters:
-  title underline width, table layout width and text wrap width.
-
-* Add stub for the :confval:`keep_warnings` configuration value in the
-  ``conf.py`` generated by sphinx-quickstart.
-
-* Speed up building the search index by caching the results of the word
-  stemming routines.  Saves about 20 seconds when building the Python
-  documentation.
-
-* #1062: sphinx.ext.autodoc use __init__ method signature for class signature.
-
-* PR#111: Respect add_autodoc_attrgetter() even when inherited-members is set.
-  Thanks to A. Jesse Jiryu Davis.
-
-* #1090: Fix gettext does not extract glossary terms.
-
-* #1070: Avoid un-pickling issues when running Python 3 and the saved
-  environment was created under Python 2.
-
-* #1069: Fixed error caused when autodoc would try to format signatures of
-  "partial" functions without keyword arguments (patch by Artur Gaspar).
-
-* The :confval:`latex_documents`, :confval:`texinfo_documents`, and
-  :confval:`man_pages` configuration values will be set to default values based
-  on the :confval:`master_doc` if not explicitly set in :file:`conf.py`.
-  Previously, if these values were not set, no output would be genereted by
-  their respective builders.
-
-* The :rst:dir:`toctree` directive and the ``toctree()`` template function now
-  have an ``includehidden`` option that includes hidden toctree entries (bugs
-  #790 and #1047). A bug in the ``maxdepth`` option for the ``toctree()``
-  template function has been fixed (bug #1046).
-
-* PR#99: Strip down seealso directives to normal admonitions.  This removes
-  their unusual CSS classes (admonition-see-also), inconsistent LaTeX
-  admonition title ("See Also" instead of "See also"), and spurious indentation
-  in the text builder.
-
-* sphinx-build now has a verbose option :option:`-v` which can be
-  repeated for greater effect.  A single occurrance provides a
-  slightly more verbose output than normal.  Two or more occurrences
-  of this option provides more detailed output which may be useful for
-  debugging.
-
-* sphinx-build now provides more specific error messages when called with
-  invalid options or arguments.
-
-* sphinx-build now supports the standard :option:`--help` and
-  :option:`--version` options.
-
-* #869: sphinx-build now has the option :option:`-T` for printing the full
-  traceback after an unhandled exception.
-
-* #976: Fix gettext does not extract index entries.
-
-* #940: Fix gettext does not extract figure caption.
-
-* #1067: Improve the ordering of the JavaScript search results: matches in titles
-  come before matches in full text, and object results are better categorized.
-  Also implement a pluggable search scorer.
-
-* Fix text writer can not handle visit_legend for figure directive contents.
-
-* PR#72: #975: Fix gettext does not extract definition terms before docutils 0.10.0
-
-* PR#25: In inheritance diagrams, the first line of the class docstring
-  is now the tooltip for the class.
-
-* PR#47: Added :mod:`sphinx.ext.linkcode` extension.
-
-* PR#75: Added ``--follow-links`` option to sphinx-apidoc.
-
-* PR#45: The linkcheck builder now checks ``#anchor``\ s for existence.
-
-* PR#28: Added Hungarian translation.
-
-* PR#35: Added Slovak translation.
-
-* PR#54: Added Norwegian bokmaal translation.
-
-* PR#52: ``special_members`` flag to autodoc now behaves like ``members``.
-
-* #955: Fix i18n transformation.
-
-* PR#74: Fix some Russian translation.
-
-* PR#97: Fix footnote handling in translated documents.
-
-* Update to jQuery 1.7.1 and Underscore.js 1.3.1.
-
-* #1055: Fix web support with relative path to source directory.
-
-* #1053: The "rightsidebar" and "collapsiblesidebar" HTML theme options now work together.
-
-* #1015: Stop overriding jQuery contains() in the JavaScript.
-
-* #1028: Fix line block output in the text builder.
-
-* #1018: Fix "container" directive handling in the text builder.
-
-* #1012: Update Estonian translation.
-
-* #1010: Make pngmath images transparent by default; IE7+ should handle it.
-
-* #440: Fix coarse timestamp resolution in some filesystem generate wrong outdated file-list.
-
-* #1008: Fix test failures with Python 3.3.
-
-* #1029: Fix intersphinx_mapping values are not stable if mapping have plural key/value set with Python 3.3.
-
-* #920: Rescue PIL packaging issue that allow import Image without PIL namespace. Thanks to Marc Schlaich.
-
-* #1024: Improve Makefile/make.bat error message if Sphinx is not found. Thanks to anatoly techtonik.
-
-* #1037: Fix typos in Polish translation. Thanks to Jakub Wilk.
-
-* #1038: Fix cpp domain parser fails to parse C+11 "static constexpr" declarations. Thanks to Jakub Wilk.
-
-* #1043: Fix sphinx-quickstart asks again and again Y|N because input() return value with extra '\r' on Python-3.2.0 + Windows. Thanks to Régis Décamps.
-
-* #1041: Fix cpp domain parser fails to parse a const type with a modifier.
-
-* #958: Do not preserve ``environment.pickle`` after a failed build.
-
-* PR#88: Added the "Sphinx Developer's Guide" (:file:`doc/devguide.rst`)
-  which outlines the basic development process of the Sphinx project.
-
-* Added the Docutils-native XML and pseudo-XML builders.  See
-  :class:`XMLBuilder` and :class:`PseudoXMLBuilder`.
+  - #1067: Improve the ordering of the JavaScript search results: matches in titles
+    come before matches in full text, and object results are better categorized.
+    Also implement a pluggable search scorer.
+  - #1053: The "rightsidebar" and "collapsiblesidebar" HTML theme options now work
+    together.
+  - Update to jQuery 1.7.1 and Underscore.js 1.3.1.
 
 * Texinfo builder
 
   - Fixed an issue where duplicate domain indices would result in invalid
     output.
 
+* LaTeX builder:
+
+  - PR#115: Add ``'transition'`` item in :confval:`latex_elements` for
+    customizing how transitions are displayed. Thanks to Jeff Klukas.
+  - PR#114: The LaTeX writer now includes the "cmap" package by default. The
+    ``'cmappkg'`` item in :confval:`latex_elements` can be used to control this.
+    Thanks to Dmitry Shachnev.
+  - The ``'fontpkg'`` item in :confval:`latex_elements` now defaults to ``''``
+    when the :confval:`language` uses the Cyrillic script.  Suggested by Dmitry
+    Shachnev.
+  - The :confval:`latex_documents`, :confval:`texinfo_documents`, and
+    :confval:`man_pages` configuration values will be set to default values based
+    on the :confval:`master_doc` if not explicitly set in :file:`conf.py`.
+    Previously, if these values were not set, no output would be genereted by
+    their respective builders.
+
+* Internationalization:
+
+  - Add i18n capabilities for custom templates.  For example: The Sphinx
+    reference documentation in doc directory provides a ``sphinx.pot`` file with
+    message strings from ``doc/_templates/*.html`` when using ``make gettext``.
+
+* Other builders:
+
+  - Added the Docutils-native XML and pseudo-XML builders.  See
+    :class:`XMLBuilder` and :class:`PseudoXMLBuilder`.
+  - PR#45: The linkcheck builder now checks ``#anchor``\ s for existence.
+  - PR#123, #1106: Add epub_use_index configuration value.  If provided, it will
+    be used instead of html_use_index for epub builder.
+
+* Extensions:
+
+  - PR#52: ``special_members`` flag to autodoc now behaves like ``members``.
+  - PR#47: Added :mod:`sphinx.ext.linkcode` extension.
+  - PR#25: In inheritance diagrams, the first line of the class docstring
+    is now the tooltip for the class.
+
+* Command-line interfaces:
+
+  - PR#75: Added ``--follow-links`` option to sphinx-apidoc.
+  - #869: sphinx-build now has the option :option:`-T` for printing the full
+    traceback after an unhandled exception.
+  - sphinx-build now supports the standard :option:`--help` and
+    :option:`--version` options.
+  - sphinx-build now provides more specific error messages when called with
+    invalid options or arguments.
+  - sphinx-build now has a verbose option :option:`-v` which can be repeated for
+    greater effect.  A single occurrance provides a slightly more verbose output
+    than normal.  Two or more occurrences of this option provides more detailed
+    output which may be useful for debugging.
+
+* Locales:
+
+  - PR#74: Fix some Russian translation.
+  - PR#54: Added Norwegian bokmaal translation.
+  - PR#35: Added Slovak translation.
+  - PR#28: Added Hungarian translation.
+  - #1113: Add Hebrew locale.
+  - #1097: Add Basque locale.
+  - #1037: Fix typos in Polish translation. Thanks to Jakub Wilk.
+  - #1012: Update Estonian translation.
+
+* Optimizations:
+
+  - Speed up building the search index by caching the results of the word
+    stemming routines.  Saves about 20 seconds when building the Python
+    documentation.
+  - PR#108: Add experimental support for parallel building with a new
+    :option:`-j` option.
+
+Documentation
+-------------
+
+* PR#88: Added the "Sphinx Developer's Guide" (:file:`doc/devguide.rst`)
+  which outlines the basic development process of the Sphinx project.
+* Added a detailed "Installing Sphinx" document (:file:`doc/install.rst`).
+
+Bugs fixed
+----------
+
+* PR#124: Fix paragraphs in versionmodified are ignored when it has no
+  dangling paragraphs.  Fix wrong html output (nested ``<p>`` tag).  Fix
+  versionmodified is not translatable.  Thanks to Nozomu Kaneko.
+* PR#111: Respect add_autodoc_attrgetter() even when inherited-members is set.
+  Thanks to A. Jesse Jiryu Davis.
+* PR#97: Fix footnote handling in translated documents.
+* Fix text writer not handling visit_legend for figure directive contents.
+* Fix text builder not respecting wide/fullwidth characters: title underline
+  width, table layout width and text wrap width.
+* Fix leading space in LaTeX table header cells.
+* #1132: Fix LaTeX table output for multi-row cells in the first column.
+* #1128: Fix Unicode errors when trying to format time strings with a
+  non-standard locale.
+* #1127: Fix traceback when autodoc tries to tokenize a non-Python file.
+* #1126: Fix double-hyphen to en-dash conversion in wrong places such as
+  command-line option names in LaTeX.
+* #1123: Allow whitespaces in filenames given to :rst:dir:`literalinclude`.
+* #1120: Added improvements about i18n for themes "basic", "haiku" and
+  "scrolls" that Sphinx built-in. Thanks to Leonardo J. Caballero G.
+* #1118: Updated Spanish translation. Thanks to Leonardo J. Caballero G.
+* #1117: Handle .pyx files in sphinx-apidoc.
+* #1112: Avoid duplicate download files when referenced from documents in
+  different ways (absolute/relative).
+* #1111: Fix failure to find uppercase words in search when
+  :confval:`html_search_language` is 'ja'. Thanks to Tomo Saito.
+* #1108: The text writer now correctly numbers enumerated lists with
+  non-default start values (based on patch by Ewan Edwards).
+* #1102: Support multi-context "with" statements in autodoc.
+* #1090: Fix gettext not extracting glossary terms.
+* #1074: Add environment version info to the generated search index to avoid
+  compatibility issues with old builds.
+* #1070: Avoid un-pickling issues when running Python 3 and the saved
+  environment was created under Python 2.
+* #1069: Fixed error caused when autodoc would try to format signatures of
+  "partial" functions without keyword arguments (patch by Artur Gaspar).
+* #1062: sphinx.ext.autodoc use __init__ method signature for class signature.
+* #1055: Fix web support with relative path to source directory.
+* #1043: Fix sphinx-quickstart asking again for yes/no questions because
+  ``input()`` returns values with an extra '\r' on Python 3.2.0 +
+  Windows. Thanks to Régis Décamps.
+* #1041: Fix failure of the cpp domain parser to parse a const type with a
+  modifier.
+* #1038: Fix failure of the cpp domain parser to parse C+11 "static constexpr"
+  declarations.  Thanks to Jakub Wilk.
+* #1029: Fix intersphinx_mapping values not being stable if the mapping has
+  plural key/value set with Python 3.3.
+* #1028: Fix line block output in the text builder.
+* #1024: Improve Makefile/make.bat error message if Sphinx is not found. Thanks
+  to Anatoly Techtonik.
+* #1018: Fix "container" directive handling in the text builder.
+* #1015: Stop overriding jQuery contains() in the JavaScript.
+* #1010: Make pngmath images transparent by default; IE7+ should handle it.
+* #1008: Fix test failures with Python 3.3.
+* #995: Fix table-of-contents and page numbering for the LaTeX "howto" class.
+* #976: Fix gettext does not extract index entries.
+* PR#72: #975: Fix gettext not extracting definition terms before docutils 0.10.
+* #961: Fix LaTeX output for triple quotes in code snippets.
+* #958: Do not preserve ``environment.pickle`` after a failed build.
+* #955: Fix i18n transformation.
+* #940: Fix gettext does not extract figure caption.
+* #920: Fix PIL packaging issue that allowed to import ``Image`` without PIL
+  namespace.  Thanks to Marc Schlaich.
+* #723: Fix the search function on local files in WebKit based browsers.
+* #440: Fix coarse timestamp resolution in some filesystem generating a wrong
+  list of outdated files.
+
 
 Release 1.1.3 (Mar 10, 2012)
 ============================
     "striptags" Jinja filter.
 
 
-Release 0.6.7 (Jun 05, 2010)
-============================
+Previous versions
+=================
 
-* #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.
+The changelog for versions before 1.0 can be found in the file ``CHANGES.old``
+in the source distribution or `at BitBucket
+<http://bitbucket.org/birkenfeld/sphinx/raw/tip/CHANGES.old>`__.
+For the changelog from version 1.0, look at the file CHANGES.
+
+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.