Changes in Sphinx¶
Release 1.2 (in development)¶
Release 1.1 (Oct 9, 2011)¶
Incompatible changes¶
- The
py:module
directive doesn’t output itsplatform
option value anymore. (It was the only thing that the directive did output, and therefore quite inconsistent.) - Removed support for old dependency versions; requirements are now:
- Pygments >= 1.2
- Docutils >= 0.7
- Jinja2 >= 2.3
Features added¶
- Added Python 3.x support.
- New builders and subsystems:
- Added a Texinfo builder.
- Added i18n support for content, a
gettext
builder and related utilities. - Added the
websupport
library and builder. - #98: Added a
sphinx-apidoc
script that autogenerates a hierarchy of source files containing autodoc directives to document modules and packages. - #273: Add an API for adding full-text search support for languages other than English. Add support for Japanese.
- Markup:
- #138: Added an
index
role, to make inline index entries. - #454: Added more index markup capabilities: marking see/seealso entries, and main entries for a given key.
- #460: Allowed limiting the depth of section numbers for HTML using the
toctree
‘snumbered
option. - #586: Implemented improved
glossary
markup which allows multiple terms per definition. - #478: Added
py:decorator
directive to describe decorators. - C++ domain now supports array definitions.
- C++ domain now supports doc fields (
:param x:
inside directives). - Section headings in
only
directives are now correctly handled. - Added
emphasize-lines
option to source code directives. - #678: C++ domain now supports superclasses.
- #138: Added an
- HTML builder:
- Added
pyramid
theme. - #559:
html_add_permalinks
is now a string giving the text to display in permalinks. - #259: HTML table rows now have even/odd CSS classes to enable “Zebra styling”.
- #554: Add theme option
sidebarwidth
to the basic theme.
- Added
- Other builders:
- #516: Added new value of the
latex_show_urls
option to show the URLs in footnotes. - #209: Added
text_newlines
andtext_sectionchars
config values. - Added
man_show_urls
config value. - #472: linkcheck builder: Check links in parallel, use HTTP HEAD
requests and allow configuring the timeout. New config values:
linkcheck_timeout
andlinkcheck_workers
. - #521: Added
linkcheck_ignore
config value. - #28: Support row/colspans in tables in the LaTeX builder.
- #516: Added new value of the
- Configuration and extensibility:
- #537: Added
nitpick_ignore
. - #306: Added
env-get-outdated
event. Application.add_stylesheet()
now accepts full URIs.
- #537: Added
- Autodoc:
- #564: Add
autodoc_docstring_signature
. When enabled (the default), autodoc retrieves the signature from the first line of the docstring, if it is found there. - #176: Provide
private-members
option for autodoc directives. - #520: Provide
special-members
option for autodoc directives. - #431: Doc comments for attributes can now be given on the same line as the assignment.
- #437: autodoc now shows values of class data attributes.
- autodoc now supports documenting the signatures of
functools.partial
objects.
- #564: Add
- Other extensions:
- Added the
sphinx.ext.mathjax
extension. - #443: Allow referencing external graphviz files.
- Added
inline
option to graphviz directives, and fixed the default (block-style) in LaTeX output. - #590: Added
caption
option to graphviz directives. - #553: Added
testcleanup
blocks in the doctest extension. - #594:
trim_doctest_flags
now also removes<BLANKLINE>
indicators. - #367: Added automatic exclusion of hidden members in inheritance diagrams, and an option to selectively enable it.
- Added
pngmath_add_tooltips
. - The math extension displaymath directives now support
name
in addition tolabel
for giving the equation label, for compatibility with Docutils.
- Added the
- New locales:
- #221: Added Swedish locale.
- #526: Added Iranian locale.
- #694: Added Latvian locale.
- Added Nepali locale.
- #714: Added Korean locale.
- #766: Added Estonian locale.
Release 1.0.9 (in development)¶
- #778: Fix “hide search matches” link on pages linked by search.
- Fix the source positions referenced by the “viewcode” extension.
Release 1.0.8 (Sep 23, 2011)¶
- #627: Fix tracebacks for AttributeErrors in autosummary generation.
- Fix the
abbr
role when the abbreviation has newlines in it. - #727: Fix the links to search results with custom object types.
- #648: Fix line numbers reported in warnings about undefined references.
- #696, #666: Fix C++ array definitions and template arguments that are not type names.
- #633: Allow footnotes in section headers in LaTeX output.
- #616: Allow keywords to be linked via intersphinx.
- #613: Allow Unicode characters in production list token names.
- #720: Add dummy visitors for graphviz nodes for text and man.
- #704: Fix image file duplication bug.
- #677: Fix parsing of multiple signatures in C++ domain.
- #637: Ignore Emacs lock files when looking for source files.
- #544: Allow .pyw extension for importable modules in autodoc.
- #700: Use
$(MAKE)
in quickstart-generated Makefiles. - #734: Make sidebar search box width consistent in browsers.
- #644: Fix spacing of centered figures in HTML output.
- #767: Safely encode SphinxError messages when printing them to sys.stderr.
- #611: Fix LaTeX output error with a document with no sections but a link target.
- Correctly treat built-in method descriptors as methods in autodoc.
- #706: Stop monkeypatching the Python textwrap module.
- #657: viewcode now works correctly with source files that have non-ASCII encoding.
- #669: Respect the
noindex
flag option in py:module directives. - #675: Fix IndexErrors when including nonexisting lines with
literalinclude
. - #676: Respect custom function/method parameter separator strings.
- #682: Fix JS incompatibility with jQuery >= 1.5.
- #693: Fix double encoding done when writing HTMLHelp .hhk files.
- #647: Do not apply SmartyPants in parsed-literal blocks.
- C++ domain now supports array definitions.
Release 1.0.7 (Jan 15, 2011)¶
- #347: Fix wrong generation of directives of static methods in autosummary.
- #599: Import PIL as
from PIL import Image
. - #558: Fix longtables with captions in LaTeX output.
- Make token references work as hyperlinks again in LaTeX output.
- #572: Show warnings by default when reference labels cannot be found.
- #536: Include line number when complaining about missing reference targets in nitpicky mode.
- #590: Fix inline display of graphviz diagrams in LaTeX output.
- #589: Build using app.build() in setup command.
- Fix a bug in the inheritance diagram exception that caused base classes to be skipped if one of them is a builtin.
- Fix general index links for C++ domain objects.
- #332: Make admonition boundaries in LaTeX output visible.
- #573: Fix KeyErrors occurring on rebuild after removing a file.
- Fix a traceback when removing files with globbed toctrees.
- If an autodoc object cannot be imported, always re-read the document containing the directive on next build.
- If an autodoc object cannot be imported, show the full traceback of the import error.
- Fix a bug where the removal of download files and images wasn’t noticed.
- #571: Implement
~
cross-reference prefix for the C domain. - Fix regression of LaTeX output with the fix of #556.
- #568: Fix lookup of class attribute documentation on descriptors so that comment documentation now works.
- Fix traceback with
only
directives preceded by targets. - Fix tracebacks occurring for duplicate C++ domain objects.
- Fix JavaScript domain links to objects with
$
in their name.
Release 1.0.6 (Jan 04, 2011)¶
- #581: Fix traceback in Python domain for empty cross-reference targets.
- #283: Fix literal block display issues on Chrome browsers.
- #383, #148: Support sorting a limited range of accented characters in the general index and the glossary.
- #570: Try decoding
-D
and-A
command-line arguments with the locale’s preferred encoding. - #528: Observe
locale_dirs
when looking for the JS translations file. - #574: Add special code for better support of Japanese documents in the LaTeX builder.
- Regression of #77: If there is only one parameter given with
:param:
markup, the bullet list is now suppressed again. - #556: Fix missing paragraph breaks in LaTeX output in certain situations.
- #567: Emit the
autodoc-process-docstring
event even for objects without a docstring so that it can add content. - #565: In the LaTeX builder, not only literal blocks require different table handling, but also quite a few other list-like block elements.
- #515: Fix tracebacks in the viewcode extension for Python objects that do not have a valid signature.
- Fix strange reportings of line numbers for warnings generated from autodoc-included docstrings, due to different behavior depending on docutils version.
- Several fixes to the C++ domain.
Release 1.0.5 (Nov 12, 2010)¶
- #557: Add CSS styles required by docutils 0.7 for aligned images and figures.
- In the Makefile generated by LaTeX output, do not delete pdf files on clean; they might be required images.
- #535: Fix LaTeX output generated for line blocks.
- #544: Allow
.pyw
as a source file extension.
Release 1.0.4 (Sep 17, 2010)¶
- #524: Open intersphinx inventories in binary mode on Windows, since version 2 contains zlib-compressed data.
- #513: Allow giving non-local URIs for JavaScript files, e.g. in the JSMath extension.
- #512: Fix traceback when
intersphinx_mapping
is empty.
Release 1.0.3 (Aug 23, 2010)¶
- #495: Fix internal vs. external link distinction for links coming from a docutils table-of-contents.
- #494: Fix the
maxdepth
option for thetoctree()
template callable when used withcollapse=True
. - #507: Fix crash parsing Python argument lists containing brackets in string literals.
- #501: Fix regression when building LaTeX docs with figures that don’t have captions.
- #510: Fix inheritance diagrams for classes that are not picklable.
- #497: Introduce separate background color for the sidebar collapse button, making it easier to see.
- #502, #503, #496: Fix small layout bugs in several builtin themes.
Release 1.0.2 (Aug 14, 2010)¶
- #490: Fix cross-references to objects of types added by the
add_object_type()
API function. - Fix handling of doc field types for different directive types.
- Allow breaking long signatures, continuing with backlash-escaped newlines.
- Fix unwanted styling of C domain references (because of a namespace clash with Pygments styles).
- Allow references to PEPs and RFCs with explicit anchors.
- #471: Fix LaTeX references to figures.
- #482: When doing a non-exact search, match only the given type of object.
- #481: Apply non-exact search for Python reference targets with
.name
for modules too. - #484: Fix crash when duplicating a parameter in an info field list.
- #487: Fix setting the default role to one provided by the
oldcmarkup
extension. - #488: Fix crash when json-py is installed, which provides a
json
module but is incompatible to simplejson. - #480: Fix handling of target naming in intersphinx.
- #486: Fix removal of
!
for all cross-reference roles.
Release 1.0.1 (Jul 27, 2010)¶
- #470: Fix generated target names for reST domain objects; they are not in the same namespace.
- #266: Add Bengali language.
- #473: Fix a bug in parsing JavaScript object names.
- #474: Fix building with SingleHTMLBuilder when there is no toctree.
- Fix display names for objects linked to by intersphinx with explicit targets.
- Fix building with the JSON builder.
- Fix hyperrefs in object descriptions for LaTeX.
Release 1.0 (Jul 23, 2010)¶
Incompatible changes¶
- Support for domains has been added. A domain is a collection of
directives and roles that all describe objects belonging together,
e.g. elements of a programming language. A few builtin domains are
provided:
- Python
- C
- C++
- JavaScript
- reStructuredText
- The old markup for defining and linking to C directives is now
deprecated. It will not work anymore in future versions without
activating the
oldcmarkup
extension; in Sphinx 1.0, it is activated by default. - Removed support for old dependency versions; requirements are now:
- docutils >= 0.5
- Jinja2 >= 2.2
- Removed deprecated elements:
exclude_dirs
config valuesphinx.builder
module
Features added¶
- General:
- Markup:
- The
menuselection
andguilabel
roles now support ampersand accelerators. - New more compact doc field syntax is now recognized:
:param type name: description
. - Added
tab-width
option toliteralinclude
directive. - Added
titlesonly
option totoctree
directive. - Added the
prepend
andappend
options to theliteralinclude
directive. - #284: All docinfo metadata is now put into the document metadata, not just the author.
- The
ref
role can now also reference tables by caption. - The
include
directive now supports absolute paths, which are interpreted as relative to the source directory. - In the Python domain, references like
:func:`.name`
now look for matching names with any prefix if no direct match is found.
- The
- Configuration:
- Added
rst_prolog
config value. - Added
html_secnumber_suffix
config value to control section numbering format. - Added
html_compact_lists
config value to control docutils’ compact lists feature. - The
html_sidebars
config value can now contain patterns as keys, and the values can be lists that explicitly select which sidebar templates should be rendered. That means that the builtin sidebar contents can be included only selectively. html_static_path
can now contain single file entries.- The new universal config value
exclude_patterns
makes the oldunused_docs
,exclude_trees
andexclude_dirnames
obsolete. - Added
html_output_encoding
config value. - Added the
latex_docclass
config value and made the “twoside” documentclass option overridable by “oneside”. - Added the
trim_doctest_flags
config value, which is true by default. - Added
html_show_copyright
config value. - Added
latex_show_pagerefs
andlatex_show_urls
config values. - The behavior of
html_file_suffix
changed slightly: the empty string now means “no suffix” instead of “default suffix”, useNone
for “default suffix”.
- Added
- New builders:
- Added a builder for the Epub format.
- Added a builder for manual pages.
- Added a single-file HTML builder.
- HTML output:
- Inline roles now get a CSS class with their name, allowing styles to
customize their appearance. Domain-specific roles get two classes,
domain
anddomain-rolename
. - References now get the class
internal
if they are internal to the whole project, as opposed to internal to the current page. - External references can be styled differently with the new
externalrefs
theme option for the default theme. - In the default theme, the sidebar can experimentally now be made
collapsible using the new
collapsiblesidebar
theme option. - #129: Toctrees are now wrapped in a
div
tag with classtoctree-wrapper
in HTML output. - The
toctree
callable in templates now has amaxdepth
keyword argument to control the depth of the generated tree. - The
toctree
callable in templates now accepts atitles_only
keyword argument. - Added
htmltitle
block in layout template. - In the JavaScript search, allow searching for object names including
the module name, like
sys.argv
. - Added new theme
haiku
, inspired by the Haiku OS user guide. - Added new theme
nature
. - Added new theme
agogo
, created by Andi Albrecht. - Added new theme
scrolls
, created by Armin Ronacher. - #193: Added a
visitedlinkcolor
theme option to the default theme. - #322: Improved responsiveness of the search page by loading the search index asynchronously.
- Inline roles now get a CSS class with their name, allowing styles to
customize their appearance. Domain-specific roles get two classes,
- Extension API:
- Added
html-collect-pages
. - Added
needs_sphinx
config value andrequire_sphinx()
application API method. - #200: Added
add_stylesheet()
application API method.
- Added
- Extensions:
- Added the
viewcode
extension. - Added the
extlinks
extension. - Added support for source ordering of members in autodoc, with
autodoc_member_order = 'bysource'
. - Added
autodoc_default_flags
config value, which can be used to select default flags for all autodoc directives. - Added a way for intersphinx to refer to named labels in other projects, and to specify the project you want to link to.
- #280: Autodoc can now document instance attributes assigned in
__init__
methods. - Many improvements and fixes to the
autosummary
extension, thanks to Pauli Virtanen. - #309: The
graphviz
extension can now output SVG instead of PNG images, controlled by thegraphviz_output_format
config value. - Added
alt
option tographviz
extension directives. - Added
exclude
argument toautodoc.between()
.
- Added the
- Translations:
- Added Croatian translation, thanks to Bojan Mihelač.
- Added Turkish translation, thanks to Firat Ozgul.
- Added Catalan translation, thanks to Pau Fernández.
- Added simplified Chinese translation.
- Added Danish translation, thanks to Hjorth Larsen.
- Added Lithuanian translation, thanks to Dalius Dobravolskas.
- Bugs fixed:
- #445: Fix links to result pages when using the search function
of HTML built with the
dirhtml
builder. - #444: In templates, properly re-escape values treated with the “striptags” Jinja filter.
- #445: Fix links to result pages when using the search function
of HTML built with the
Release 0.6.7 (Jun 05, 2010)¶
- #440: Remove usage of a Python >= 2.5 API in the
literalinclude
directive. - Fix a bug that prevented some references being generated in the LaTeX builder.
- #428: Add some missing CSS styles for standard docutils classes.
- #432: Fix UnicodeErrors while building LaTeX in translated locale.
Release 0.6.6 (May 25, 2010)¶
- Handle raw nodes in the
text
writer. - Fix a problem the Qt help project generated by the
qthelp
builder that would lead to no content being displayed in the Qt Assistant. - #393: Fix the usage of Unicode characters in mathematic formulas
when using the
pngmath
extension. - #404: Make
\and
work properly in the author field of thelatex_documents
setting. - #409: Make the
highlight_language
config value work properly in the LaTeX builder. - #418: Allow relocation of the translation JavaScript files to the system directory on Unix systems.
- #414: Fix handling of Windows newlines in files included with
the
literalinclude
directive. - #377: Fix crash in linkcheck builder.
- #387: Fix the display of search results in
dirhtml
output. - #376: In autodoc, fix display of parameter defaults containing backslashes.
- #370: Fix handling of complex list item labels in LaTeX output.
- #374: Make the
doctest_path
config value of the doctest extension actually work. - Fix the handling of multiple toctrees when creating the global
TOC for the
toctree()
template function. - Fix the handling of hidden toctrees when creating the global TOC
for the
toctree()
template function. - Fix the handling of nested lists in the text writer.
- #362: In autodoc, check for the existence of
__self__
on function objects before accessing it. - #353: Strip leading and trailing whitespace when extracting search words in the search function.
Release 0.6.5 (Mar 01, 2010)¶
- In autodoc, fix the omission of some module members explicitly documented using documentation comments.
- #345: Fix cropping of sidebar scroll bar with
stickysidebar
option of the default theme. - #341: Always generate UNIX newlines in the quickstart Makefile.
- #338: Fix running with
-C
under Windows. - In autodoc, allow customizing the signature of an object where the built-in mechanism fails.
- #331: Fix output for enumerated lists with start values in LaTeX.
- Make the
start-after
andend-before
options to theliteralinclude
directive work correctly if not used together. - #321: Fix link generation in the LaTeX builder.
Release 0.6.4 (Jan 12, 2010)¶
- Improve the handling of non-Unicode strings in the configuration.
- #316: Catch OSErrors occurring when calling graphviz with arguments it doesn’t understand.
- Restore compatibility with Pygments >= 1.2.
- #295: Fix escaping of hyperref targets in LaTeX output.
- #302: Fix links generated by the
:doc:
role for LaTeX output. - #286: collect todo nodes after the whole document has been read; this allows placing substitution references in todo items.
- #294: do not ignore an explicit
today
config value in a LaTeX build. - The
alt
text of inheritance diagrams is now much cleaner. - Ignore images in section titles when generating link captions.
- #310: support exception messages in the
testoutput
blocks of thedoctest
extension. - #293: line blocks are styled properly in HTML output.
- #285: make the
locale_dirs
config value work again. - #303:
html_context
values given on the command line via-A
should not override other values given in conf.py. - Fix a bug preventing incremental rebuilds for the
dirhtml
builder. - #299: Fix the mangling of quotes in some literal blocks.
- #292: Fix path to the search index for the
dirhtml
builder. - Fix a Jython compatibility issue: make the dependence on the
parser
module optional. - #238: In autodoc, catch all errors that occur on module import,
not just
ImportError
. - Fix the handling of non-data, but non-method descriptors in autodoc.
- When copying file times, ignore OSErrors raised by
os.utime()
.
Release 0.6.3 (Sep 03, 2009)¶
- Properly add C module filenames as dependencies in autodoc.
- #253: Ignore graphviz directives without content instead of raising an unhandled exception.
- #241: Fix a crash building LaTeX output for documents that contain a todolist directive.
- #252: Make it easier to change the build dir in the Makefiles generated by quickstart.
- #220: Fix CSS so that displaymath really is centered.
- #222: Allow the “Footnotes” header to be translated.
- #225: Don’t add whitespace in generated HTML after inline tags.
- #227: Make
literalinclude
work when the document’s path name contains non-ASCII characters. - #229: Fix autodoc failures with members that raise errors
on
getattr()
. - #205: When copying files, don’t copy full stat info, only modification times.
- #232: Support non-ASCII metadata in Qt help builder.
- Properly format bullet lists nested in definition lists for LaTeX.
- Section titles are now allowed inside
only
directives. - #201: Make
centered
directive work in LaTeX output. - #206: Refuse to overwrite an existing master document in sphinx-quickstart.
- #208: Use MS-sanctioned locale settings, determined by the
language
config option, in the HTML help builder. - #210: Fix nesting of HTML tags for displayed math from pngmath extension.
- #213: Fix centering of images in LaTeX output.
- #211: Fix compatibility with docutils 0.5.
Release 0.6.2 (Jun 16, 2009)¶
- #130: Fix obscure IndexError in doctest extension.
- #167: Make glossary sorting case-independent.
- #196: Add a warning if an extension module doesn’t have a
setup()
function. - #158: Allow ‘..’ in template names, and absolute template paths; Jinja 2 by default disables both.
- When highlighting Python code, ignore extra indentation before trying to parse it as Python.
- #191: Don’t escape the tilde in URIs in LaTeX.
- Don’t consider contents of source comments for the search index.
- Set the default encoding to
utf-8-sig
to handle files with a UTF-8 BOM correctly. - #178: apply
add_function_parentheses
config value to C functions as promised. - #173: Respect the docutils
title
directive. - #172: The
obj
role now links to modules as promised. - #19: Tables now can have a “longtable” class, in order to get correctly broken into pages in LaTeX output.
- Look for Sphinx message catalogs in the system default path before
trying
sphinx/locale
. - Fix the search for methods via “classname.methodname”.
- #155: Fix Python 2.4 compatibility: exceptions are old-style classes there.
- #150: Fix display of the “sphinxdoc” theme on Internet Explorer versions 6 and 7.
- #146: Don’t fail to generate LaTeX when the user has an active
.docutils
configuration. - #29: Don’t generate visible “-{-}” in option lists in LaTeX.
- Fix cross-reference roles when put into substitutions.
- Don’t put image “alt” text into table-of-contents entries.
- In the LaTeX writer, do not raise an exception on too many section levels, just use the “subparagraph” level for all of them.
- #145: Fix autodoc problem with automatic members that refuse to be getattr()’d from their parent.
- If specific filenames to build are given on the command line, check that they are within the source directory.
- Fix autodoc crash for objects without a
__name__
. - Fix intersphinx for installations without urllib2.HTTPSHandler.
- #134: Fix pending_xref leftover nodes when using the todolist directive from the todo extension.
Release 0.6.1 (Mar 26, 2009)¶
- #135: Fix problems with LaTeX output and the graphviz extension.
- #132: Include the autosummary “module” template in the distribution.
Release 0.6 (Mar 24, 2009)¶
New features added¶
Incompatible changes:
Templating now requires the Jinja2 library, which is an enhanced version of the old Jinja1 engine. Since the syntax and semantic is largely the same, very few fixes should be necessary in custom templates.
The “document” div tag has been moved out of the
layout.html
template’s “document” block, because the closing tag was already outside. If you overwrite this block, you need to remove your “document” div tag as well.The
autodoc_skip_member
event now also gets to decide whether to skip members whose name starts with underscores. Previously, these members were always automatically skipped. Therefore, if you handle this event, add something like this to your event handler to restore the old behavior:if name.startswith('_'): return True
Theming support, see the new section in the documentation.
Markup:
- 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. - #4: 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. - #10: Added HTML section numbers, enabled by giving a
:numbered:
flag to thetoctree
directive. - #114: Added an
abbr
role to markup abbreviations and acronyms. - 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. - #123: The
glossary
directive now supports a:sorted:
flag that sorts glossary entries alphabetically. - 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. - #52: There is now a
hlist
directive, creating a compact list by placing distributing items into multiple columns. - #77: If a description environment with info field list only
contains one
:param:
entry, no bullet list is generated. - #6: Don’t generate redundant
<ul>
for top-level TOC tree items, which leads to a visual separation of TOC entries. - #23: Added a
classmethod
directive along withmethod
andstaticmethod
. - Scaled images now get a link to the unscaled version.
- SVG images are now supported in HTML (via
<object>
and<embed>
tags). - Added a
toctree
callable to the templates, and the ability to include external links in toctrees. The ‘collapse’ keyword argument indicates whether or not to only display subitems of the current page. (Defaults to True.)
- Due to popular demand, added a
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 inlatex_elements
) to the build directory.
- The new config value
Builders:
- The HTML builder now stores a small file named
.buildinfo
in its output directory. It stores a hash of config values that can be used to determine if a full rebuild needs to be done (e.g. after changinghtml_theme
). - New builder for Qt help collections, by Antonio Valentino.
- The new
DirectoryHTMLBuilder
(short namedirhtml
) creates a separate directory for every page, and places the page there in a file calledindex.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.
- The HTML builder now stores a small file named
New translations:
- Italian by Sandro Dentella.
- Ukrainian by Petro Sasnyk.
- Finnish by Jukka Inkeri.
- Russian by Alexander Smishlajev.
Extensions and API:
- New
graphviz
extension to embed graphviz graphs. - New
inheritance_diagram
extension to embed... inheritance diagrams! - 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 amember-order
option per directive. - The function
Sphinx.add_directive()
now also supports docutils 0.5-style directive classes. If they inherit fromsphinx.util.compat.Directive
, they also work with docutils 0.4. - There is now a
Sphinx.add_lexer()
method to be able to use custom Pygments lexers easily. - There is now
Sphinx.add_generic_role()
to mirror the docutils’ own function.
- New
Other changes:
- Config overrides for single dict keys can now be given on the command line.
- There is now a
doctest_global_setup
config value that can be used to give setup code for all doctests in the documentation. - Source links in HTML are now generated with
rel="nofollow"
. - Quickstart can now generate a Windows
make.bat
file. - #62: 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.
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
andpngmath_dvipng
options are no longer split into command and additional arguments; usepngmath_latex_args
andpngmath_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 docutilsmeta
directive are now supported. SerializingHTMLBuilder
was added as new abstract builder that can be subclassed to serialize build HTML in a specific format. ThePickleHTMLBuilder
is a concrete subclass of it that uses pickle as serialization implementation.JSONHTMLBuilder
was added as anotherSerializingHTMLBuilder
subclass that dumps the generated HTML into JSON files for further processing.- The
rellinks
block in the layout template is now calledlinktags
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.
- Incompatible change: The “root” relation link (top left in the
relbar) now points to the
- New and changed config values:
- Added support for internationalization in generated text with the
language
andlocale_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.
- Added support for internationalization in generated text with the
- Extensions:
- The new extensions
sphinx.ext.jsmath
andsphinx.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
andplatform
options.
- The new extensions
- 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 fileconf.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.
- Added a command-line switch
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 anencoding
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
andshow-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 aglob
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 thetabulary
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 thelatex_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
andwarning
. - 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 thesphinx/jinja
directory that may be left over from old revisions.The clumsy handling of the
index.html
template was removed. The config valuehtml_index
is gone, andhtml_additional_pages
should be used instead. If you need it, the oldindex.html
template is still there, calleddefindex.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
inhtml_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 likeadd_description_unit
but the directive will only create a target and no output. - Support a new method,
add_transform
. It takes a standard docutilsTransform
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).
- Support a new method,
- 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.
- New directive,
- Templates (HTML output):
index.html
renamed todefindex.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.
- The
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.