Sphinx 1.3¶

Release 1.3.6 (released Feb 29, 2016)¶

Features added¶

#1873, #1876, #2278: Add page_source_suffix html context variable. This should be introduced with source_parsers feature. Thanks for Eric Holscher.

Bugs fixed¶

#2265: Fix babel is used in spite of disabling it on latex_elements
#2295: Avoid mutating dictionary errors while enumerating members in autodoc with Python 3
#2291: Fix pdflatex “Counter too large” error from footnotes inside tables of contents
#2292: Fix some footnotes disappear from LaTeX output
#2287: sphinx.transforms.Locale always uses rst parser. Sphinx i18n feature should support parsers that specified source_parsers.
#2290: Fix sphinx.ext.mathbase use of amsfonts may break user choice of math fonts
#2324: Print a hint how to increase the recursion limit when it is hit.
#1565, #2229: Revert new warning; the new warning will be triggered from version 1.4 on.
#2329: Refresh environment forcedly if source directory has changed.
#2019: Fix the domain objects in search result are not escaped

Release 1.3.5 (released Jan 24, 2016)¶

Bugs fixed¶

Fix line numbers was not shown on warnings in LaTeX and texinfo builders
Fix filenames were not shown on warnings of citations
Fix line numbers was not shown on warnings in LaTeX and texinfo builders
Fix line numbers was not shown on warnings of indices
#2026: Fix LaTeX builder raises error if parsed-literal includes links
#2243: Ignore strange docstring types for classes, do not crash
#2247: Fix #2205 breaks make html for definition list with classifiers that contains regular-expression like string
#1565: Sphinx will now emit a warning that highlighting was skipped if the syntax is incorrect for code-block, literalinclude and so on.
#2211: Fix paragraphs in table cell doesn’t work in Latex output
#2253: :pyobject: option of literalinclude directive can’t detect indented body block when the block starts with blank or comment lines.
Fix TOC is not shown when no :maxdepth: for toctrees (ref: #771)
Fix warning message for :numref: if target is in orphaned doc (ref: #2244)

Release 1.3.4 (released Jan 12, 2016)¶

Bugs fixed¶

#2134: Fix figure caption with reference causes latex build error
#2094: Fix rubric with reference not working in Latex
#2147: Fix literalinclude code in latex does not break in pages
#1833: Fix email addresses is showed again if latex_show_urls is not None
#2176: sphinx.ext.graphviz: use <object> instead of <img> to embed svg
#967: Fix SVG inheritance diagram is not hyperlinked (clickable)
#1237: Fix footnotes not working in definition list in LaTeX
#2168: Fix raw directive does not work for text writer
#2171: Fix cannot linkcheck url with unicode
#2182: LaTeX: support image file names with more than 1 dots
#2189: Fix previous sibling link for first file in subdirectory uses last file, not intended previous from root toctree
#2003: Fix decode error under python2 (only) when make linkcheck is run
#2186: Fix LaTeX output of mathbb in math
#1480, #2188: LaTeX: Support math in section titles
#2071: Fix same footnote in more than two section titles => LaTeX/PDF Bug
#2040: Fix UnicodeDecodeError in sphinx-apidoc when author contains non-ASCII characters
#2193: Fix shutil.SameFileError if source directory and destination directory are same
#2178: Fix unparsable C++ cross-reference when referencing a function with :cpp:any:
#2206: Fix Sphinx latex doc build failed due to a footnotes
#2201: Fix wrong table caption for tables with over 30 rows
#2213: Set <blockquote> in the classic theme to fit with <p>
#1815: Fix linkcheck does not raise an exception if warniserror set to true and link is broken
#2197: Fix slightly cryptic error message for missing index.rst file
#1894: Unlisted phony targets in quickstart Makefile
#2125: Fix unifies behavior of collapsed fields (GroupedField and TypedField)
#1408: Check latex_logo validity before copying
#771: Fix latex output doesn’t set tocdepth
#1820: On Windows, console coloring is broken with colorama version 0.3.3. Now Sphinx use colorama>=0.3.5 to avoid this problem.
#2072: Fix footnotes in chapter-titles do not appear in PDF output
#1580: Fix paragraphs in longtable don’t work in Latex output
#1366: Fix centered image not centered in latex
#1860: Fix man page using :samp: with braces - font doesn’t reset
#1610: Sphinx crashes in Japanese indexing in some systems
Fix Sphinx crashes if mecab initialization failed
#2160: Fix broken TOC of PDFs if section includes an image
#2172: Fix dysfunctional admonition \py@lightbox in sphinx.sty. Thanks to jfbu.
#2198,#2205: make gettext generate broken msgid for definition lists.
#2062: Escape characters in doctests are treated incorrectly with Python 2.
#2225: Fix if the option does not begin with dash, linking is not performed
#2226: Fix math is not HTML-encoded when :nowrap: is given (jsmath, mathjax)
#1601, #2220: ‘any’ role breaks extended domains behavior. Affected extensions doesn’t support resolve_any_xref and resolve_xref returns problematic node instead of None. sphinxcontrib-httpdomain is one of them.
#2229: Fix no warning is given for unknown options

Release 1.3.3 (released Dec 2, 2015)¶

Bugs fixed¶

#2177: Fix parallel hangs
#2012: Fix exception occurred if numfig_format is invalid
#2142: Provide non-minified JS code in sphinx/search/non-minified-js/*.js for source distribution on PyPI.
#2148: Error while building devhelp target with non-ASCII document.

Release 1.3.2 (released Nov 29, 2015)¶

Features added¶

#1935: Make “numfig_format” overridable in latex_elements.

Bugs fixed¶

#1976: Avoid “2.0” version of Babel because it doesn’t work with Windows environment.
Add a “default.css” stylesheet (which imports “classic.css”) for compatibility
#1788: graphviz extension raises exception when caption option is present.
#1789: :pyobject: option of literalinclude directive includes following lines after class definitions
#1790: literalinclude strips empty lines at the head and tail
#1802: load plugin themes automatically when theme.conf use it as ‘inherit’. Thanks to Takayuki Hirai.
#1794: custom theme extended from alabaster or sphinx_rtd_theme can’t find base theme.
#1834: compatibility for Docutils 0.13: handle_io_errors keyword argument for docutils.io.FileInput cause TypeError.
#1823: ‘.’ as <module_path> for sphinx-apidoc cause an unfriendly error. Now ‘.’ is converted to absolute path automatically.
Fix a crash when setting up extensions which do not support metadata.
#1784: Provide non-minified JS code in sphinx/search/non-minified-js/*.js
#1822, #1892: Fix regression for #1061. autosummary can’t generate doc for imported members since Sphinx 1.3b3. Thanks to Eric Larson.
#1793, #1819: “see also” misses a linebreak in text output. Thanks to Takayuki Hirai.
#1780, #1866: “make text” shows “class” keyword twice. Thanks to Takayuki Hirai.
#1871: Fix for LaTeX output of tables with one column and multirows.
Work around the lack of the HTMLParserError exception in Python 3.5.
#1949: Use safe_getattr in the coverage builder to avoid aborting with descriptors that have custom behavior.
#1915: Do not generate smart quotes in doc field type annotations.
#1796: On py3, automated .mo building caused UnicodeDecodeError.
#1923: Use babel features only if the babel latex element is nonempty.
#1942: Fix a KeyError in websupport.
#1903: Fix strange id generation for glossary terms.
make text will crush if a definition list item has more than 1 classifiers as: term : classifier1 : classifier2.
#1855: make gettext generates broken po file for definition lists with classifier.
#1869: Fix problems when dealing with files containing non-ASCII characters. Thanks to Marvin Schmidt.
#1798: Fix building LaTeX with references in titles.
#1725: On py2 environment, doctest with using non-ASCII characters causes 'ascii' codec can't decode byte exception.
#1540: Fix RuntimeError with circular referenced toctree
#1983: i18n translation feature breaks references which uses section name.
#1990: Use caption of toctree to title of tableofcontents in LaTeX
#1987: Fix ampersand is ignored in :menuselection: and :guilabel: on LaTeX builder
#1994: More supporting non-standard parser (like recommonmark parser) for Translation and WebSupport feature. Now node.rawsource is fall backed to node.astext() during Docutils transforming.
#1989: “make blahblah” on Windows indicate help messages for sphinx-build every time. It was caused by wrong make.bat that generated by Sphinx 1.3.0/1.3.1.
On Py2 environment, conf.py that is generated by sphinx-quickstart should have u prefixed config value for ‘version’ and ‘release’.
#2102: On Windows + Py3, using |today| and non-ASCII date format will raise UnicodeEncodeError.
#1974: UnboundLocalError: local variable ‘domain’ referenced before assignment when using any role and sphinx.ext.intersphinx in same time.
#2121: multiple words search doesn’t find pages when words across on the page title and the page content.
#1884, #1885: plug-in html themes cannot inherit another plug-in theme. Thanks to Suzumizaki.
#1818: sphinx.ext.todo directive generates broken html class attribute as ‘admonition-’ when language is specified with non-ASCII linguistic area like ‘ru’ or ‘ja’. To fix this, now todo directive can use :class: option.
#2140: Fix footnotes in table has broken in LaTeX
#2127: MecabBinder for html searching feature doesn’t work with Python 3. Thanks to Tomoko Uchida.

Release 1.3.1 (released Mar 17, 2015)¶

Bugs fixed¶

#1769: allows generating quickstart files/dirs for destination dir that doesn’t overwrite existent files/dirs. Thanks to WAKAYAMA shirou.
#1773: sphinx-quickstart doesn’t accept non-ASCII character as a option argument.
#1766: the message “least Python 2.6 to run” is at best misleading.
#1772: cross reference in docstrings like :param .write: breaks building.
#1770, #1774: literalinclude with empty file occurs exception. Thanks to Takayuki Hirai.
#1777: Sphinx 1.3 can’t load extra theme. Thanks to tell-k.
#1776: source_suffix = ['.rst'] cause unfriendly error on prior version.
#1771: automated .mo building doesn’t work properly.
#1783: Autodoc: Python2 Allow unicode string in __all__. Thanks to Jens Hedegaard Nielsen.
#1781: Setting html_domain_indices to a list raises a type check warnings.

Release 1.3 (released Mar 10, 2015)¶

Incompatible changes¶

Roles ref, term and menusel now don’t generate emphasis nodes anymore. If you want to keep italic style, adapt your stylesheet.
Role numref uses %s as special character to indicate position of figure numbers instead # symbol.

Features added¶

Add convenience directives and roles to the C++ domain: directive cpp:var as alias for cpp:member, role :cpp:var as alias for :cpp:member, and role any for cross-reference to any C++ declaraction. #1577, #1744
The source_suffix config value can now be a list of multiple suffixes.
Add the ability to specify source parsers by source suffix with the source_parsers config value.
#1675: A new builder, AppleHelpBuilder, has been added that builds Apple Help Books.

Bugs fixed¶

1.3b3 change breaks a previous gettext output that contains duplicated msgid such as “foo bar” and “version changes in 1.3: foo bar”.
#1745: latex builder cause maximum recursion depth exceeded when a footnote has a footnote mark itself.
#1748: SyntaxError in sphinx/ext/ifconfig.py with Python 2.6.
#1658, #1750: No link created (and warning given) if option does not begin with -, / or +. Thanks to Takayuki Hirai.
#1753: C++, added missing support for more complex declarations.
#1700: Add :caption: option for toctree.
#1742: :name: option is provided for toctree, code-block and literalinclude directives.
#1756: Incorrect section titles in search that was introduced from 1.3b3.
#1746: C++, fixed name lookup procedure, and added missing lookups in declarations.
#1765: C++, fix old id generation to use fully qualified names.

Documentation¶

#1651: Add vartype field description for python domain.

Release 1.3b3 (released Feb 24, 2015)¶

Incompatible changes¶

Dependency requirement updates: Docutils 0.11, Pygments 2.0
The gettext_enables config value has been renamed to gettext_additional_targets.
#1735: Use https://docs.python.org/ instead of http protocol. It was used for sphinx.ext.intersphinx and some documentation.

Features added¶

#1346: Add new default theme;
- Add ‘alabaster’ theme.
- Add ‘sphinx_rtd_theme’ theme.
- The ‘default’ html theme has been renamed to ‘classic’. ‘default’ is still available, however it will emit notice a recommendation that using new ‘alabaster’ theme.
Added highlight_options configuration value.
The language config value is now available in the HTML templates.
The env-updated event can now return a value, which is interpreted as an iterable of additional docnames that need to be rewritten.
#772: Support for scoped and unscoped enums in C++. Enumerators in unscoped enums are injected into the parent scope in addition to the enum scope.
Add todo_include_todos config option to quickstart conf file, handled as described in documentation.
HTML breadcrumb items tag has class “nav-item” and “nav-item-N” (like nav-item-0, 1, 2…).
New option sphinx-quickstart --use-make-mode for generating Makefile that use sphinx-build make-mode.
#1235: i18n: several node can be translated if it is set to gettext_additional_targets in conf.py. Supported nodes are:
- ‘literal-block’
- ‘doctest-block’
- ‘raw’
- ‘image’
#1227: Add html_scaled_image_link config option to conf.py, to control scaled image link.

Bugs fixed¶

LaTeX writer now generates correct markup for cells spanning multiple rows.
#1674: Do not crash if a module’s __all__ is not a list of strings.
#1629: Use VerbatimBorderColor to add frame to code-block in LaTeX
On windows, make-mode didn’t work on Win32 platform if Sphinx was invoked as python sphinx-build.py.
#1687: linkcheck now treats 401 Unauthorized responses as “working”.
#1690: toctrees with glob option now can also contain entries for single documents with explicit title.
#1591: html search results for C++ elements now has correct interpage links.
bizstyle theme: nested long title pages make long breadcrumb that breaks page layout.
bizstyle theme: all breadcrumb items become ‘Top’ on some mobile browser (iPhone5s safari).
#1722: restore toctree() template function behavior that was changed at 1.3b1.
#1732: i18n: localized table caption raises exception.
#1718: :numref: does not work with capital letters in the label
#1630: resolve CSS conflicts, div.container css target for literal block wrapper now renamed to div.literal-block-wrapper.
sphinx.util.pycompat has been restored in its backwards-compatibility; slated for removal in Sphinx 1.4.
#1719: LaTeX writer does not respect numref_format option in captions

Release 1.3b2 (released Dec 5, 2014)¶

Incompatible changes¶

update bundled ez_setup.py for setuptools-7.0 that requires Python 2.6 or later.

Features added¶

#1597: Added possibility to return a new template name from html-page-context.
PR#314, #1150: Configuration values are now checked for their type. A warning is raised if the configured and the default value do not have the same type and do not share a common non-trivial base class.

Bugs fixed¶

PR#311: sphinx-quickstart does not work on python 3.4.
Fix autodoc_docstring_signature not working with signatures in class docstrings.
Rebuilding cause crash unexpectedly when source files were added.
#1607: Fix a crash when building latexpdf with “howto” class
#1251: Fix again. Sections which depth are lower than :tocdepth: should not be shown on localtoc sidebar.
make-mode didn’t work on Win32 platform if Sphinx was installed by wheel package.

Release 1.3b1 (released Oct 10, 2014)¶

Incompatible changes¶

Dropped support for Python 2.5, 3.1 and 3.2.
Dropped support for Docutils versions up to 0.9.
Removed the sphinx.ext.oldcmarkup extension.
The deprecated config values exclude_trees, exclude_dirnames and unused_docs have been removed.
A new node, sphinx.addnodes.literal_strong, has been added, for text that should appear literally (i.e. no smart quotes) in strong font. Custom writers will have to be adapted to handle this node.
PR#269, #1476: replace <tt> tag by <code>. User customized stylesheets should be updated If the css contain some styles for tt> tag. Thanks to Takeshi Komiya.
#1543: templates_path is automatically added to exclude_patterns to avoid reading autosummary rst templates in the templates directory.
Custom domains should implement the new Domain.resolve_any_xref method to make the any role work properly.
gettext builder: gettext doesn’t emit uuid information to generated pot files by default. Please set True to gettext_uuid to emit uuid information. Additionally, if the python-levenshtein 3rd-party package is installed, it will improve the calculation time.
gettext builder: disable extracting/apply ‘index’ node by default. Please set ‘index’ to gettext_enables to enable extracting index entries.
PR#307: Add frame to code-block in LaTeX. Thanks to Takeshi Komiya.

Features added¶

Add support for Python 3.4.
Add support for Docutils 0.12
Added sphinx.ext.napoleon extension for NumPy and Google style docstring support.
Added support for parallel reading (parsing) of source files with the sphinx-build -j option. Third-party extensions will need to be checked for compatibility and may need to be adapted if they store information in the build environment object. See env-merge-info.
Added the any role that can be used to find a cross-reference of any type in any domain. Custom domains should implement the new Domain.resolve_any_xref method to make this work properly.
Exception logs now contain the last 10 messages emitted by Sphinx.
Added support for extension versions (a string returned by setup(), these can be shown in the traceback log files). Version requirements for extensions can be specified in projects using the new needs_extensions config value.
Changing the default role within a document with the default-role directive is now supported.
PR#214: Added stemming support for 14 languages, so that the built-in document search can now handle these. Thanks to Shibukawa Yoshiki.
PR#296, PR#303, #76: numfig feature: Assign numbers to figures, tables and code-blocks. This feature is configured with numfig, numfig_secnum_depth and numfig_format. Also numref role is available. Thanks to Takeshi Komiya.
PR#202: Allow “.” and “~” prefixed references in :param: doc fields for Python.
PR#184: Add autodoc_mock_imports, allowing to mock imports of external modules that need not be present when autodocumenting.
#925: Allow list-typed config values to be provided on the command line, like -D key=val1,val2.
#668: Allow line numbering of code-block and literalinclude directives to start at an arbitrary line number, with a new lineno-start option.
PR#172, PR#266: The code-block and literalinclude directives now can have a caption option that shows a filename before the code in the output. Thanks to Nasimul Haque, Takeshi Komiya.
Prompt for the document language in sphinx-quickstart.
PR#217: Added config values to suppress UUID and location information in generated gettext catalogs.
PR#236, #1456: apidoc: Add a -M option to put module documentation before submodule documentation. Thanks to Wes Turner and Luc Saffre.
#1434: Provide non-minified JS files for jquery.js and underscore.js to clarify the source of the minified files.
PR#252, #1291: Windows color console support. Thanks to meu31.
PR#255: When generating latex references, also insert latex target/anchor for the ids defined on the node. Thanks to Olivier Heurtier.
PR#229: Allow registration of other translators. Thanks to Russell Sim.
Add app.set_translator() API to register or override a Docutils translator class like html_translator_class.
PR#267, #1134: add ‘diff’ parameter to literalinclude. Thanks to Richard Wall and WAKAYAMA shirou.
PR#272: Added ‘bizstyle’ theme. Thanks to Shoji KUMAGAI.
Automatically compile *.mo files from *.po files when gettext_auto_build is True (default) and *.po is newer than *.mo file.
#623: sphinx.ext.viewcode supports imported function/class aliases.
PR#275: sphinx.ext.intersphinx supports multiple target for the inventory. Thanks to Brigitta Sipocz.
PR#261: Added the env-before-read-docs event that can be connected to modify the order of documents before they are read by the environment.
#1284: Program options documented with option can now start with +.
PR#291: The caption of code-block is recognized as a title of ref target. Thanks to Takeshi Komiya.
PR#298: Add new API: add_latex_package(). Thanks to Takeshi Komiya.
#1344: add gettext_enables to enable extracting ‘index’ to gettext catalog output / applying translation catalog to generated documentation.
PR#301, #1583: Allow the line numbering of the directive literalinclude to match that of the included file, using a new lineno-match option. Thanks to Jeppe Pihl.
PR#299: add various options to sphinx-quickstart. Quiet mode option --quiet will skips wizard mode. Thanks to WAKAYAMA shirou.
#1623: Return types specified with :rtype: are now turned into links if possible.

Bugs fixed¶

#1438: Updated jQuery version from 1.8.3 to 1.11.1.
#1568: Fix a crash when a “centered” directive contains a reference.
Now sphinx.ext.autodoc works with python-2.5 again.
#1563: add_search_language() raises AssertionError for correct type of argument. Thanks to rikoman.
#1174: Fix smart quotes being applied inside roles like program or makevar.
PR#235: comment db schema of websupport lacked a length of the node_id field. Thanks to solos.
#1466,PR#241: Fix failure of the cpp domain parser to parse C+11 “variadic templates” declarations. Thanks to Victor Zverovich.
#1459,PR#244: Fix default mathjax js path point to http:// that cause mixed-content error on HTTPS server. Thanks to sbrandtb and robo9k.
PR#157: autodoc remove spurious signatures from @property decorated attributes. Thanks to David Ham.
PR#159: Add coverage targets to quickstart generated Makefile and make.bat. Thanks to Matthias Troffaes.
#1251: When specifying toctree :numbered: option and :tocdepth: metadata, sub section number that is larger depth than :tocdepth: is shrunk.
PR#260: Encode underscore in citation labels for latex export. Thanks to Lennart Fricke.
PR#264: Fix could not resolve xref for figure node with :name: option. Thanks to Takeshi Komiya.
PR#265: Fix could not capture caption of graphviz node by xref. Thanks to Takeshi Komiya.
PR#263, #1013, #1103: Rewrite of C++ domain. Thanks to Jakob Lykke Andersen.
- Hyperlinks to all found nested names and template arguments (#1103).
- Support for function types everywhere, e.g., in std::function<bool(int, int)> (#1013).
- Support for virtual functions.
- Changed interpretation of function arguments to following standard prototype declarations, i.e., void f(arg) means that arg is the type of the argument, instead of it being the name.
- Updated tests.
- Updated documentation with elaborate description of what declarations are supported and how the namespace declarations influence declaration and cross-reference lookup.
- Index names may be different now. Elements are indexed by their fully qualified name. It should be rather easy to change this behaviour and potentially index by namespaces/classes as well.
PR#258, #939: Add dedent option for code-block and literalinclude. Thanks to Zafar Siddiqui.
PR#268: Fix numbering section does not work at singlehtml mode. It still ad-hoc fix because there is a issue that section IDs are conflicted. Thanks to Takeshi Komiya.
PR#273, #1536: Fix RuntimeError with numbered circular toctree. Thanks to Takeshi Komiya.
PR#274: Set its URL as a default title value if URL appears in toctree. Thanks to Takeshi Komiya.
PR#276, #1381: rfc and pep roles support custom link text. Thanks to Takeshi Komiya.
PR#277, #1513: highlights for function pointers in argument list of c:function. Thanks to Takeshi Komiya.
PR#278: Fix section entries were shown twice if toctree has been put under only directive. Thanks to Takeshi Komiya.
#1547: pgen2 tokenizer doesn’t recognize ... literal (Ellipsis for py3).
PR#294: On LaTeX builder, wrap float environment on writing literal_block to avoid separation of caption and body. Thanks to Takeshi Komiya.
PR#295, #1520: make.bat latexpdf mechanism to cd back to the current directory. Thanks to Peter Suter.
PR#297, #1571: Add imgpath property to all builders. It make easier to develop builder extensions. Thanks to Takeshi Komiya.
#1584: Point to master doc in HTML “top” link.
#1585: Autosummary of modules broken in Sphinx 1.2.3.
#1610: Sphinx cause AttributeError when MeCab search option is enabled and python-mecab is not installed.
#1674: Do not crash if a module’s __all__ is not a list of strings.
#1673: Fix crashes with nitpick_ignore and :doc: references.
#1686: ifconfig directive doesn’t care about default config values.
#1642: Fix only one search result appearing in Chrome.

Documentation¶

Add clarification about the syntax of tags. (doc/markup/misc.rst)