Sphinx 0.6 and 0.5.2, beta 1, released

Georg Brandl georg at python.org
Tue Mar 17 00:15:18 CET 2009

Hi all,

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

* General/Markup:

  - 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
    ``<embed>`` tags).

* 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 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
    command line.

  - 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
    into errors.


More information about the Python-announce-list mailing list