Sphinx 0.5

Release 0.5.2 (Mar 24, 2009)

• Properly escape | in LaTeX output.

• #71: If a decoding error occurs in source files, print a warning and replace the characters by “?”.

• Fix a problem in the HTML search if the index takes too long to load.

• Don’t output system messages while resolving, because they would stay in the doctrees even if keep_warnings is false.

• #82: Determine the correct path for dependencies noted by docutils. This fixes behavior where a source with dependent files was always reported as changed.

• Recognize toctree directives that are not on section toplevel, but within block items, such as tables.

• Use a new RFC base URL, since rfc.org seems down.

• Fix a crash in the todolist directive when no todo items are defined.

• Don’t call LaTeX or dvipng over and over again if it was not found once, and use text-only latex as a substitute in that case.

• Fix problems with footnotes in the LaTeX output.

• Prevent double hyphens becoming en-dashes in literal code in the LaTeX output.

• Open literalinclude files in universal newline mode to allow arbitrary newline conventions.

• Actually make the -Q option work.

• #86: Fix explicit document titles in toctrees.

• #81: Write environment and search index in a manner that is safe from exceptions that occur during dumping.

• #80: Fix UnicodeErrors when a locale is set with setlocale().

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.

Previous

Sphinx 0.6

Next

Sphinx 0.4