Sphinx Changelog

What's new in Sphinx 1.2.1

Feb 27, 2014

Bugs fixed:
#1335: Fix autosummary template overloading with exclamation prefix like ``{% extends "!autosummary/class.rst" %}`` cause infinite recursive function call. This was caused by PR#181.
#1337: Fix autodoc with ``autoclass_content="both"`` uses useless ``object.__init__`` docstring when class does not have ``__init__``. This was caused by a change for #1138.
#1340: Can't search alphabetical words on the HTML quick search generated with language='ja'.
#1319: Do not crash if the :confval:`html_logo` file does not exist.
#603: Do not use the HTML-ized title for building the search index (that resulted in "literal" being found on every page with a literal in the title).
#751: Allow production lists longer than a page in LaTeX by using longtable.
#764: Always look for stopwords lowercased in JS search.
#814: autodoc: Guard against strange type objects that don't have ``__bases__``.
#932: autodoc: Do not crash if ``__doc__`` is not a string.
#933: Do not crash if an :rst:role:`option` value is malformed (contains spaces but no option name).
#908: On Python 3, handle error messages from LaTeX correctly in the pngmath extension.
#943: In autosummary, recognize "first sentences" to pull from the docstring if they contain uppercase letters.
#923: Take the entire LaTeX document into account when caching pngmath-generated images. This rebuilds them correctly when :confval:`pngmath_latex_preamble` changes.
#901: Emit a warning when using docutils' new "math" markup without a Sphinx math extension active.
#845: In code blocks, when the selected lexer fails, display line numbers nevertheless if configured.
#929: Support parsed-literal blocks in LaTeX output correctly.
#949: Update the tabulary.sty packed with Sphinx.
#1050: Add anonymous labels into ``objects.inv`` to be referenced via :mod:`~sphinx.ext.intersphinx`.
#1095: Fix print-media stylesheet being included always in the "scrolls" theme.
#1085: Fix current classname not getting set if class description has ``:noindex:`` set.
#1181: Report option errors in autodoc directives more gracefully.
#1155: Fix autodocumenting C-defined methods as attributes in Python 3.
#1233: Allow finding both Python classes and exceptions with the "class" and "exc" roles in intersphinx.
#1198: Allow "image" for the "figwidth" option of the :rst:dir:`figure` directive as documented by docutils.
#1152: Fix pycode parsing errors of Python 3 code by including two grammar versions for Python 2 and 3, and loading the appropriate version for the running Python version.
#1017: Be helpful and tell the user when the argument to :rst:dir:`option` does not match the required format.
#1345: Fix two bugs with :confval:`nitpick_ignore`; now you don't have to remove the store environment for changes to have effect.
#1072: In the JS search, fix issues searching for upper-cased words by lowercasing words before stemming.
#1299: Make behavior of the :rst:dir:`math` directive more consistent and avoid producing empty environments in LaTeX output.
#1308: Strip HTML tags from the content of "raw" nodes before feeding it to the search indexer.
#1249: Fix duplicate LaTeX page numbering for manual documents.
#1292: In the linkchecker, retry HEAD requests when denied by HTTP 405. Also make the redirect code apparent and tweak the output a bit to be more obvious.
#1285: Avoid name clashes between C domain objects and section titles.
#848: Always take the newest code in incremental rebuilds with the :mod:`sphinx.ext.viewcode` extension.
#979, #1266: Fix exclude handling in ``sphinx-apidoc``.
#1302: Fix regression in :mod:`sphinx.ext.inheritance_diagram` when documenting classes that can't be pickled.
#1316: Remove hard-coded ``font-face`` resources from epub theme.
#1329: Fix traceback with empty translation msgstr in .po files.
#1300: Fix references not working in translated documents in some instances.
#1283: Fix a bug in the detection of changed files that would try to access doctrees of deleted documents.
#1330: Fix :confval:`exclude_patterns` behavior with subdirectories in the :confval:`html_static_path`.
#1323: Fix emitting empty ```` tags in the HTML writer, which is not valid HTML.
#1147: Don't emit a sidebar search box in the "singlehtml" builder.

New in Sphinx 1.1.2 (Nov 2, 2011)

New in Sphinx 1.0.6 (Jan 5, 2011)

New in Sphinx 1.0.5 (Nov 12, 2010)

New in Sphinx 1.0.4 (Sep 17, 2010)

New in Sphinx 1.0.1 (Jul 28, 2010)

New in Sphinx 1.0 Beta 1 (May 25, 2010)

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.
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.
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.
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.
Extension API:
Added ``html-collect-pages`` event.
Added ``needs_sphinx`` config value and ``Sphinx.require_sphinx`` application API function.
#200: Added ``Sphinx.add_stylesheet()``.
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.
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.

New in Sphinx 0.6.5 (Mar 2, 2010)

New in Sphinx 0.6.4 (Jan 14, 2010)

New in Sphinx 0.6.2 (Jun 17, 2009)

New in Sphinx 0.6 Beta 1 (Mar 17, 2009)

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 ```` 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 ```` and ```` 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.
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.