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 ``block``\s 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 ```` 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.