Sphinx 1.4¶

Release 1.4.9 (released Nov 23, 2016)¶

Bugs fixed¶

#2936: Fix doc/Makefile that can’t build man because doc/man exists
#3058: Using the same ‘caption’ attribute in multiple ‘toctree’ directives results in warning / error
#3068: Allow the ‘=’ character in the -D option of sphinx-build.py
#3074: add_source_parser() crashes in debug mode
#3135: sphinx.ext.autodoc crashes with plain Callable
#3150: Fix query word splitter in JavaScript. It behaves as same as Python’s regular expression.
#3093: gettext build broken on substituted images.
#3093: gettext build broken on image node under note directive.
imgmath: crashes on showing error messages if image generation failed
#3117: LaTeX writer crashes if admonition is placed before first section title
#3164: Change search order of sphinx.ext.inheritance_diagram

Release 1.4.8 (released Oct 1, 2016)¶

Bugs fixed¶

#2996: The wheel package of Sphinx got crash with ImportError

Release 1.4.7 (released Oct 1, 2016)¶

Bugs fixed¶

#2890: Quickstart should return an error consistently on all error conditions
#2870: flatten genindex columns’ heights.
#2856: Search on generated HTML site doesn’t find some symbols
#2882: Fall back to a GET request on 403 status in linkcheck
#2902: jsdump.loads fails to load search index if keywords starts with underscore
#2900: Fix epub content.opf: add auto generated orphan files to spine.
#2899: Fix hasdoc() function in Jinja2 template. It will detect genindex, search also.
#2901: Fix epub result: skip creating links from image tags to original image files.
#2917: inline code is hyphenated on HTML
#1462: autosummary warns for namedtuple with attribute with trailing underscore
Could not reference equations if :nowrap: option specified
#2873: code-block overflow in latex (due to commas)
#1060, #2056: sphinx.ext.intersphinx: broken links are generated if relative paths are used in intersphinx_mapping
#2931: code-block directive with same :caption: causes warning of duplicate target. Now code-block and literalinclude does not define hyperlink target using its caption automatically.
#2962: latex: missing label of longtable
#2968: autodoc: show-inheritance option breaks docstrings

Release 1.4.6 (released Aug 20, 2016)¶

Incompatible changes¶

#2867: linkcheck builder crashes with six-1.4. Now Sphinx depends on six-1.5 or later

Bugs fixed¶

applehelp: Sphinx crashes if hiutil or codesign commands not found
Fix make clean abort issue when build dir contains regular files like DS_Store.
Reduce epubcheck warnings/errors:
- Fix DOCTYPE to html5
- Change extension from .html to .xhtml.
- Disable search page on epub results
#2778: Fix autodoc crashes if obj.__dict__ is a property method and raises exception
Fix duplicated toc in epub3 output.
#2775: Fix failing linkcheck with servers not supporting identity encoding
#2833: Fix formatting instance annotations in ext.autodoc.
#1911: -D option of sphinx-build does not override the extensions variable
#2789: sphinx.ext.intersphinx generates wrong hyperlinks if the inventory is given
parsing errors for caption of code-blocks are displayed in document (ref: #2845)
#2846: singlehtml builder does not include figure numbers
#2816: Fix data from builds cluttering the Domain.initial_data class attributes

Release 1.4.5 (released Jul 13, 2016)¶

Incompatible changes¶

latex, inclusion of non-inline images from image directive resulted in non-coherent whitespaces depending on original image width; new behaviour by necessity differs from earlier one in some cases. (ref: #2672)
latex, use of \includegraphics to refer to Sphinx custom variant is deprecated; in future it will revert to original LaTeX macro, custom one already has alternative name \sphinxincludegraphics.

Features added¶

new config option latex_keep_old_macro_names, defaults to True. If False, lets macros (for text styling) be defined only with \sphinx-prefixed names
latex writer allows user customization of “shadowed” boxes (topics), via three length variables.
woff-format web font files now supported by the epub builder.

Bugs fixed¶

jsdump fix for python 3: fixes the HTML search on python > 3
#2676: (latex) Error with verbatim text in captions since Sphinx 1.4.4
#2629: memoir class crashes LaTeX. Fixed by latex_keep_old_macro_names=False (ref 2675)
#2684: sphinx.ext.intersphinx crashes with six-1.4.1
#2679: float package needed for 'figure_align': 'H' latex option
#2671: image directive may lead to inconsistent spacing in pdf
#2705: toctree generates empty bullet_list if :titlesonly: specified
#2479: sphinx.ext.viewcode uses python2 highlighter by default
#2700: HtmlHelp builder has hard coded index.html
latex, since 1.4.4 inline literal text is followed by spurious space
#2722: C++, fix id generation for var/member declarations to include namespaces.
latex, images (from image directive) in lists or quoted blocks did not obey indentation (fixed together with #2671)
#2733: since Sphinx 1.4.4 make latexpdf generates lots of hyperref warnings
#2731: sphinx.ext.autodoc does not access propertymethods which raises any exceptions
#2666: C++, properly look up nested names involving constructors.
#2579: Could not refer a label including both spaces and colons via sphinx.ext.intersphinx
#2718: Sphinx crashes if the document file is not readable
#2699: hyperlinks in help HTMLs are broken if html_file_suffix is set
#2723: extra spaces in latex pdf output from multirow cell
#2735: latexpdf Underfull \hbox (badness 10000) warnings from title page
#2667: latex crashes if resized images appeared in section title
#2763: (html) Provide default value for required alt attribute for image tags of SVG source, required to validate and now consistent w/ other formats.

Release 1.4.4 (released Jun 12, 2016)¶

Bugs fixed¶

#2630: latex: sphinx.sty notice environment formatting problem
#2632: Warning directives fail in quote environment latex build
#2633: Sphinx crashes with old styled indices
Fix a \begin{\minipage} typo in sphinx.sty from 1.4.2 (ref: 68becb1)
#2622: Latex produces empty pages after title and table of contents
#2640: 1.4.2 LaTeX crashes if code-block inside warning directive
Let LaTeX use straight quotes also in inline code (ref #2627)
#2351: latex crashes if enumerated lists are placed on footnotes
#2646: latex crashes if math contains twice empty lines
#2480: sphinx.ext.autodoc: memory addresses were shown
latex: allow code-blocks appearing inside lists and quotes at maximal nesting depth (ref #777, #2624, #2651)
#2635: Latex code directives produce inconsistent frames based on viewing resolution
#2639: Sphinx now bundles iftex.sty
Failed to build PDF with framed.sty 0.95
Sphinx now bundles needspace.sty

Release 1.4.3 (released Jun 5, 2016)¶

Bugs fixed¶

#2530: got “Counter too large” error on building PDF if large numbered footnotes existed in admonitions
width option of figure directive does not work if align option specified at same time (ref: #2595)
#2590: The inputenc package breaks compiling under lualatex and xelatex
#2540: date on latex front page use different font
Suppress “document isn’t included in any toctree” warning if the document is included (ref: #2603)
#2614: Some tables in PDF output will end up shifted if user sets non zero parindent in preamble
#2602: URL redirection breaks the hyperlinks generated by sphinx.ext.intersphinx
#2613: Show warnings if merged extensions are loaded
#2619: make sure amstext LaTeX package always loaded (ref: d657225, 488ee52, 9d82cad and #2615)
#2593: latex crashes if any figures in the table

Release 1.4.2 (released May 29, 2016)¶

Features added¶

Now suppress_warnings accepts following configurations (ref: #2451, #2466):
- app.add_node
- app.add_directive
- app.add_role
- app.add_generic_role
- app.add_source_parser
- image.data_uri
- image.nonlocal_uri
#2453: LaTeX writer allows page breaks in topic contents; and their horizontal extent now fits in the line width (with shadow in margin). Also warning-type admonitions allow page breaks and their vertical spacing has been made more coherent with the one for hint-type notices (ref #2446).
#2459: the framing of literal code-blocks in LaTeX output (and not only the code lines themselves) obey the indentation in lists or quoted blocks.
#2343: the long source lines in code-blocks are wrapped (without modifying the line numbering) in LaTeX output (ref #1534, #2304).

Bugs fixed¶

#2370: the equations are slightly misaligned in LaTeX writer
#1817, #2077: suppress pep8 warnings on conf.py generated by sphinx-quickstart
#2407: building docs crash if document includes large data image URIs
#2436: Sphinx does not check version by needs_sphinx if loading extensions failed
#2397: Setup shorthandoff for Turkish documents
#2447: VerbatimBorderColor wrongly used also for captions of PDF
#2456: C++, fix crash related to document merging (e.g., singlehtml and Latex builders).
#2446: latex(pdf) sets local tables of contents (or more generally topic nodes) in unbreakable boxes, causes overflow at bottom
#2476: Omit MathJax markers if :nowrap: is given
#2465: latex builder fails in case no caption option is provided to toctree directive
Sphinx crashes if self referenced toctree found
#2481: spelling mistake for mecab search splitter. Thanks to Naoki Sato.
#2309: Fix could not refer “indirect hyperlink targets” by ref-role
intersphinx fails if mapping URL contains any port
#2088: intersphinx crashes if the mapping URL requires basic auth
#2304: auto line breaks in latexpdf codeblocks
#1534: Word wrap long lines in Latex verbatim blocks
#2460: too much white space on top of captioned literal blocks in PDF output
Show error reason when multiple math extensions are loaded (ref: #2499)
#2483: any figure number was not assigned if figure title contains only non text objects
#2501: Unicode subscript numbers are normalized in LaTeX
#2492: Figure directive with :figwidth: generates incorrect Latex-code
The caption of figure is always put on center even if :align: was specified
#2526: LaTeX writer crashes if the section having only images
#2522: Sphinx touches mo files under installed directory that caused permission error.
#2536: C++, fix crash when an immediately nested scope has the same name as the current scope.
#2555: Fix crash on any-references with unicode.
#2517: wrong bookmark encoding in PDF if using LuaLaTeX
#2521: generated Makefile causes BSD make crashed if sphinx-build not found
#2470: typing backport package causes autodoc errors with python 2.7
sphinx.ext.intersphinx crashes if non-string value is used for key of intersphinx_mapping
#2518: intersphinx_mapping disallows non alphanumeric keys
#2558: unpack error on devhelp builder
#2561: Info builder crashes when a footnote contains a link
#2565: The descriptions of objects generated by sphinx.ext.autosummary overflow lines at LaTeX writer
Extend pdflatex config in sphinx.sty to subparagraphs (ref: #2551)
#2445: rst_prolog and rst_epilog affect to non reST sources
#2576: sphinx.ext.imgmath crashes if subprocess raises error
#2577: sphinx.ext.imgmath: Invalid argument are passed to dvisvgm
#2556: Xapian search does not work with Python 3
#2581: The search doesn’t work if language=”es” (Spanish)
#2382: Adjust spacing after abbreviations on figure numbers in LaTeX writer
#2383: The generated footnote by latex_show_urls overflows lines
#2497, #2552: The label of search button does not fit for the button itself

Release 1.4.1 (released Apr 12, 2016)¶

Incompatible changes¶

The default format of today_fmt and html_last_updated_fmt is back to strftime format again. Locale Date Markup Language is also supported for backward compatibility until Sphinx 1.5.

Translations¶

Added Welsh translation, thanks to Geraint Palmer.
Added Greek translation, thanks to Stelios Vitalis.
Added Esperanto translation, thanks to Dinu Gherman.
Added Hindi translation, thanks to Purnank H. Ghumalia.
Added Romanian translation, thanks to Razvan Stefanescu.

Bugs fixed¶

C++, added support for extern and thread_local.
C++, type declarations are now using the prefixes typedef, using, and type, depending on the style of declaration.
#2413: C++, fix crash on duplicate declarations
#2394: Sphinx crashes when html_last_updated_fmt is invalid
#2408: dummy builder not available in Makefile and make.bat
#2412: hyperlink targets are broken in LaTeX builder
figure directive crashes if non paragraph item is given as caption
#2418: time formats no longer allowed in today_fmt
#2395: Sphinx crashes if unicode character in image filename
#2396: “too many values to unpack” in genindex-single
#2405: numref link in PDF jumps to the wrong location
#2414: missing number in PDF hyperlinks to code listings
#2440: wrong import for gmtime. Thanks to Uwe L. Korn.

Release 1.4 (released Mar 28, 2016)¶

Incompatible changes¶

Drop PorterStemmer package support. Use PyStemmer instead of PorterStemmer to accelerate stemming.
sphinx_rtd_theme has become optional. Please install it manually. Refs #2087, #2086, #1845 and #2097. Thanks to Victor Zverovich.
#2231: Use DUrole instead of DUspan for custom roles in LaTeX writer. It enables to take title of roles as an argument of custom macros.
#2022: ‘Thumbs.db’ and ‘.DS_Store’ are added to exclude_patterns default values in conf.py that will be provided on sphinx-quickstart.
#2027, #2208: The html_title accepts string values only. And the None value cannot be accepted.
sphinx.ext.graphviz: show graph image in inline by default
#2060, #2224: The manpage role now generate sphinx.addnodes.manpage node instead of sphinx.addnodes.literal_emphasis node.
#2022: html_extra_path also copies dotfiles in the extra directory, and refers to exclude_patterns to exclude extra files and directories.
#2300: enhance autoclass:: to use the docstring of __new__ if __init__ method’s is missing of empty
#2251: Previously, under glossary directives, multiple terms for one definition are converted into single term node and the each terms in the term node are separated by termsep node. In new implementation, each terms are converted into individual term nodes and termsep node is removed. By this change, output layout of every builders are changed a bit.
The default highlight language is now Python 3. This means that source code is highlighted as Python 3 (which is mostly a superset of Python 2), and no parsing is attempted to distinguish valid code. To get the old behavior back, add highlight_language = "python" to conf.py.
Locale Date Markup Language like "MMMM dd, YYYY" is default format for today_fmt and html_last_updated_fmt. However strftime format like "%B %d, %Y" is also supported for backward compatibility until Sphinx 1.5. Later format will be disabled from Sphinx 1.5.
#2327: latex_use_parts is deprecated now. Use latex_toplevel_sectioning instead.
#2337: Use \url{URL} macro instead of \href{URL}{URL} in LaTeX writer.
#1498: manpage writer: don’t make whole of item in definition list bold if it includes strong node.
#582: Remove hint message from quick search box for html output.
#2378: Sphinx now bundles newfloat.sty

Features added¶

#2092: add todo directive support in napoleon package.
#1962: when adding directives, roles or nodes from an extension, warn if such an element is already present (built-in or added by another extension).
#1909: Add “doc” references to Intersphinx inventories.
C++ type alias support (e.g., .. type:: T = int).
C++ template support for classes, functions, type aliases, and variables (#1729, #1314).
C++, added new scope management directives namespace-push and namespace-pop.
#1970: Keyboard shortcuts to navigate Next and Previous topics
Intersphinx: Added support for fetching Intersphinx inventories with URLs using HTTP basic auth.
C++, added support for template parameter in function info field lists.
C++, added support for pointers to member (function).
#2113: Allow :class: option to code-block directive.
#2192: Imgmath (pngmath with svg support).
#2200: Support XeTeX and LuaTeX for the LaTeX builder.
#1906: Use xcolor over color for fcolorbox where available for LaTeX output.
#2216: Texinputs makefile improvements.
#2170: Support for Chinese language search index.
#2214: Add sphinx.ext.githubpages to publish the docs on GitHub Pages
#1030: Make page reference names for latex_show_pagerefs translatable
#2162: Add Sphinx.add_source_parser() to add source_suffix and source_parsers from extension
#2207: Add sphinx.parsers.Parser class; a base class for new parsers
#656: Add graphviz_dot option to graphviz directives to switch the dot command
#1939: Added the dummy builder: syntax check without output.
#2230: Add math_number_all option to number all displayed math in math extensions
#2235: needs_sphinx supports micro version comparison
#2282: Add “language” attribute to html tag in the “basic” theme
#1779: Add EPUB 3 builder
#1751: Add todo_link_only to avoid file path and line indication on todolist. Thanks to Francesco Montesano.
#2199: Use imagesize package to obtain size of images.
#1099: Add configurable retries to the linkcheck builder. Thanks to Alex Gaynor. Also don’t check anchors starting with !.
#2300: enhance autoclass:: to use the docstring of __new__ if __init__ method’s is missing of empty
#1858: Add Sphinx.add_enumerable_node() to add enumerable nodes for numfig feature
#1286, #2099: Add sphinx.ext.autosectionlabel extension to allow reference sections using its title. Thanks to Tadhg O’Higgins.
#1854: Allow to choose Janome for Japanese splitter.
#1853: support custom text splitter on html search with language='ja'.
#2320: classifier of glossary terms can be used for index entries grouping key The classifier also be used for translation. See also Glossary.
#2308: Define \tablecontinued macro to redefine the style of continued label for longtables.
Select an image by similarity if multiple images are globbed by .. image:: filename.*
#1921: Support figure substitutions by language and figure_language_filename
#2245: Add latex_elements["passoptionstopackages"] option to call PassOptionsToPackages in early stage of preambles.
#2340: Math extension: support alignment of multiple equations for MathJax.
#2338: Define \titleref macro to redefine the style of title-reference roles.
Define \menuselection and \accelerator macros to redefine the style of menuselection roles.
Define \crossref macro to redefine the style of references
#2301: Texts in the classic html theme should be hyphenated.
#2355: Define \termref macro to redefine the style of term roles.
Add suppress_warnings to suppress arbitrary warning message (experimental)
#2229: Fix no warning is given for unknown options
#2327: Add latex_toplevel_sectioning to switch the top level sectioning of LaTeX document.

Bugs fixed¶

#1913: C++, fix assert bug for enumerators in next-to-global and global scope.
C++, fix parsing of ‘signed char’ and ‘unsigned char’ as types.
C++, add missing support for ‘friend’ functions.
C++, add missing support for virtual base classes (thanks to Rapptz).
C++, add support for final classes.
C++, fix parsing of types prefixed with ‘enum’.
#2023: Dutch search support uses Danish stemming info.
C++, add support for user-defined literals.
#1804: Now html output wraps overflowed long-line-text in the sidebar. Thanks to Hassen ben tanfous.
#2183: Fix porterstemmer causes make json to fail.
#1899: Ensure list is sent to OptParse.
#2164: Fix wrong check for pdftex inside sphinx.sty (for graphicx package option).
#2165, #2218: Remove faulty and non-need conditional from sphinx.sty.
Fix broken LaTeX code is generated if unknown language is given
#1944: Fix rst_prolog breaks file-wide metadata
#2074: make gettext should use canonical relative paths for .pot. Thanks to anatoly techtonik.
#2311: Fix sphinx.ext.inheritance_diagram raises AttributeError
#2251: Line breaks in .rst files are transferred to .pot files in a wrong way.
#794: Fix date formatting in latex output is not localized
Remove image/gif from supported_image_types of LaTeX writer (#2272)
Fix ValueError is raised if LANGUAGE is empty string
Fix unpack warning is shown when the directives generated from Sphinx.add_crossref_type is used
The default highlight language is now default. This means that source code is highlighted as Python 3 (which is mostly a superset of Python 2) if possible. To get the old behavior back, add highlight_language = "python" to conf.py.
#2329: Refresh environment forcedly if source directory has changed.
#2331: Fix code-blocks are filled by block in dvi; remove xcdraw option from xcolor package
Fix the confval type checker emits warnings if unicode is given to confvals which expects string value
#2360: Fix numref in LaTeX output is broken
#2361: Fix additional paragraphs inside the “compound” directive are indented
#2364: Fix KeyError ‘rootSymbol’ on Sphinx upgrade from older version.
#2348: Move amsmath and amssymb to before fontpkg on LaTeX writer.
#2368: Ignore emacs lock files like .#foo.rst by default.
#2262: literal_block and its caption has been separated by pagebreak in LaTeX output.
#2319: Fix table counter is overridden by code-block’s in LaTeX. Thanks to jfbu.
Fix unpack warning if combined with 3rd party domain extensions.
#1153: Fix figures in sidebar causes latex build error.
#2358: Fix user-preamble could not override the tocdepth definition.
#2358: Reduce tocdepth if part or chapter is used for top_sectionlevel
#2351: Fix footnote spacing
#2363: Fix toctree() in templates generates broken links in SingleHTMLBuilder.
#2366: Fix empty hyperref is generated on toctree in HTML builder.

Documentation¶

#1757: Fix for usage of html_last_updated_fmt. Thanks to Ralf Hemmecke.