Sphinx logo

Table Of Contents

Previous topic

Glossary

Next topic

Projects using Sphinx

This Page

Quick search

Changes in Sphinx

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 blocks 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.