Sphinx 0.6 and 0.5.2, beta 1, released
georg at python.org
Tue Mar 17 00:15:18 CET 2009
I'm proud to announce the release of Sphinx 0.6b1 and 0.5.2b1.
Sphinx 0.5.2 is a bugfix-only release in the 0.5 series, while 0.6 is
a feature release, containing all of 0.5.2's fixes together with
many added features.
These are beta releases, so please test them out and report any bugs
to sphinx-dev at googlegroups.com or the tracker at
<http://bitbucket.org/birkenfeld/sphinx/>. Thank you!
The finals will be out in a week's time, if no severe problems are
What is it?
Sphinx is a tool that makes it easy to create intelligent and beautiful
documentation for Python projects (or other documents consisting of
multiple reStructuredText source files).
Websites: 0.5 series <http://sphinx.pocoo.org/>
0.6 series <http://sphinx.pocoo.org/latest/>
What's new in 0.6 (short version)?
Long version: http://sphinx.pocoo.org/latest/changes.html
- Templating now requires the Jinja2 library, which is an enhanced
version of the old Jinja1 engine.
- Theming support, see the new section in the documentation.
- 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.
- 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.
- Added HTML section numbers, enabled by giving a
``:numbered:`` flag to the ``toctree`` directive.
- 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.
- 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.
- SVG images are now supported in HTML (via ``<object>`` and
- 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.
- 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
- 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.
* New command-line features:
- Config overrides for single dict keys can now be given on the
- Source links in HTML are now generated with ``rel="nofollow"``.
- Quickstart can now generate a Windows ``make.bat`` file.
- 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
More information about the Python-announce-list