
Changes in Sphinx
*****************


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 ``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
  ``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 ``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 *-n* command-line switch or
    the ``nitpicky`` config value.

  * Added ``latexpdf`` target in quickstart Makefile.

* Markup:

  * The ``menuselection`` and ``guilabel`` roles now support ampersand
    accelerators.

  * New more compact doc field syntax is now recognized: ``:param type
    name: description``.

  * Added ``tab-width`` option to ``literalinclude`` directive.

  * Added ``titlesonly`` option to ``toctree`` directive.

  * Added the ``prepend`` and ``append`` options to the
    ``literalinclude`` directive.

  * #284: All docinfo metadata is now put into the document metadata,
    not just the author.

  * The ``ref`` role can now also reference tables by caption.

  * The ``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 ``rst_prolog`` config value.

  * Added ``html_secnumber_suffix`` config value to control section
    numbering format.

  * Added ``html_compact_lists`` config value to control docutils'
    compact lists feature.

  * The ``html_sidebars`` config value can now contain patterns as
    keys, and the values can be lists that explicitly select which
    sidebar templates should be rendered.  That means that the builtin
    sidebar contents can be included only selectively.

  * ``html_static_path`` can now contain single file entries.

  * The new universal config value ``exclude_patterns`` makes the old
    ``unused_docs``, ``exclude_trees`` and ``exclude_dirnames``
    obsolete.

  * Added ``html_output_encoding`` config value.

  * Added the ``latex_docclass`` config value and made the "twoside"
    documentclass option overridable by "oneside".

  * Added the ``trim_doctest_flags`` config value, which is true by
    default.

  * Added ``html_show_copyright`` config value.

  * Added ``latex_show_pagerefs`` and ``latex_show_urls`` config
    values.

  * The behavior of ``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 ``toctree`` callable in templates now has a ``maxdepth``
    keyword argument to control the depth of the generated tree.

  * The ``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 ``html-collect-pages``.

  * Added ``needs_sphinx`` config value and ``require_sphinx()``
    application API method.

  * #200: Added ``add_stylesheet()`` application API method.

* Extensions:

  * Added the ``viewcode`` extension.

  * Added the ``extlinks`` extension.

  * Added support for source ordering of members in autodoc, with
    ``autodoc_member_order = 'bysource'``.

  * Added ``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 ``autosummary`` extension,
    thanks to Pauli Virtanen.

  * #309: The ``graphviz`` extension can now output SVG instead of PNG
    images, controlled by the ``graphviz_output_format`` config value.

  * Added ``alt`` option to ``graphviz`` extension directives.

  * Added ``exclude`` argument to ``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.
