=========================================
Incompatible changes
--------------------
* Removed ``sphinx.util.compat.directive_dwim()`` and
``sphinx.roles.xfileref_role()`` which were deprecated since version 1.0.
* PR122: the files given in ``latex_additional_files`` now override TeX
files included by Sphinx, such as ``sphinx.sty``.
* PR124: the node generated by ``versionadded``,
``versionchanged`` and ``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.
* PR99: the :rst:dir:`seealso` directive now generates admonition nodes instead
of the custom ``seealso`` node.
Features added
--------------
* Markup
- 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).
- PR99: 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.
* HTML builder
- 783: Create a link to full size image if it is scaled with width or height.
- 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
- An "Index" node is no longer added when there are no entries.
- "deffn" categories are no longer capitalized if they contain capital
letters.
- ``desc_annotation`` nodes are now rendered.
- ``strong`` and ``emphasis`` nodes are now formatted like
``literal``\s. The reason for this is because the standard Texinfo markup
(``*strong*`` and ``_emphasis_``) resulted in confusing output due to the
common usage of using these constructs for documenting parameter names.
- Field lists formatting has been tweaked to better display
"Info field lists".
- ``system_message`` and ``problematic`` nodes are now formatted in a similar
fashion as done by the text builder.
- "en-dash" and "em-dash" conversion of hyphens is no longer performed in
option directive signatures.
- ``ref`` is now used instead of ``pxref`` for cross-references which
prevents the word "see" from being added before the link (does not affect
the Info output).
- The ``finalout`` command has been added for better TeX output.
- ``transition`` nodes are now formatted using underscores ("_") instead of
asterisks ("*").
- The default value for the ``paragraphindent`` has been changed from 2 to 0
meaning that paragraphs are no longer indented by default.
- 1110: A new configuration value ``texinfo_no_detailmenu`` has been
added for controlling whether a ``detailmenu`` is added in the "Top"
node's menu.
- Detailed menus are no longer created except for the "Top" node.
- Fixed an issue where duplicate domain indices would result in invalid
output.
* LaTeX builder:
- PR115: Add ``'transition'`` item in ``latex_elements`` for
customizing how transitions are displayed. Thanks to Jeff Klukas.
- PR114: The LaTeX writer now includes the "cmap" package by default. The
``'cmappkg'`` item in ``latex_elements`` can be used to control this.
Thanks to Dmitry Shachnev.
- The ``'fontpkg'`` item in ``latex_elements`` now defaults to ``''``
when the :confval:`language` uses the Cyrillic script. Suggested by Dmitry
Shachnev.
- The ``latex_documents``, ``texinfo_documents``, and
``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 generated 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``.
- PR61,703: Add support for non-ASCII filename handling.
* Other builders:
- Added the Docutils-native XML and pseudo-XML builders. See
:class:`~sphinx.builders.xml.XMLBuilder` and
:class:`~sphinx.builders.xml.PseudoXMLBuilder`.
- PR45: The linkcheck builder now checks ``anchor``\ s for existence.
- PR123, 1106: Add ``epub_use_index`` configuration value. If
provided, it will be used instead of ``html_use_index`` for epub
builder.
- PR126: Add ``epub_tocscope`` configuration value. The setting
controls the generation of the epub toc. The user can now also include
hidden toc entries.
- PR112: Add ``epub_show_urls`` configuration value.
* Extensions:
- PR52: ``special_members`` flag to autodoc now behaves like ``members``.
- PR47: Added :mod:`sphinx.ext.linkcode` extension.
- PR25: In inheritance diagrams, the first line of the class docstring
is now the tooltip for the class.
* Command-line interfaces:
- PR75: Added ``--follow-links`` option to sphinx-apidoc.
- 869: sphinx-build now has the option ``-T`` for printing the full
traceback after an unhandled exception.
- sphinx-build now supports the standard ``--help`` and ``--version`` options.
- sphinx-build now provides more specific error messages when called with
invalid options or arguments.
- sphinx-build now has a verbose option ``-v`` which can be repeated for
greater effect. A single occurrence 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:
- PR74: Fix some Russian translation.
- PR54: Added Norwegian bokmaal translation.
- PR35: Added Slovak translation.
- PR28: 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.
- PR108: Add experimental support for parallel building with a new
:option:`sphinx-build -j` option.
Documentation
-------------
* PR88: 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
----------
* PR124: 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.
* PR111: Respect add_autodoc_attrgetter() even when inherited-members is set.
Thanks to A. Jesse Jiryu Davis.
* PR97: 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 ``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
``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.
* PR72: 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.