Sphinx 1.5

Release 1.5.6 (released May 15, 2017)

Bugs fixed

  • #3614: Sphinx crashes with requests-2.5.0

  • #3618: autodoc crashes with tupled arguments

  • #3664: No space after the bullet in items of a latex list produced by Sphinx

  • #3657: EPUB builder crashes if a document starting with genindex exists

  • #3588: No compact (p tag) html output in the i18n document build even when html_compact_lists is True.

  • #3685: AttributeError when using 3rd party domains

  • #3702: LaTeX writer styles figure legends with a hard-coded \small

  • #3708: LaTeX writer allows irc scheme

  • #3717: Stop enforcing that favicon’s must be .ico

  • #3731, #3732: Protect isenumclass predicate against non-class arguments

  • #3320: Warning about reference target not being found for container types

  • Misspelled ARCHIVEPREFIX in Makefile for latex build repertory

Release 1.5.5 (released Apr 03, 2017)

Bugs fixed

  • #3597: python domain raises UnboundLocalError if invalid name given

  • #3599: Move to new MathJax CDN

Release 1.5.4 (released Apr 02, 2017)

Features added

  • #3470: Make genindex support all kinds of letters, not only Latin ones

Bugs fixed

  • #3445: setting 'inputenc' key to \\usepackage[utf8x]{inputenc} leads to failed PDF build

  • EPUB file has duplicated nav.xhtml link in content.opf except first time build

  • #3488: objects.inv has broken when release or version contain return code

  • #2073, #3443, #3490: gettext builder that writes pot files unless the content are same without creation date. Thanks to Yoshiki Shibukawa.

  • #3487: intersphinx: failed to refer options

  • #3496: latex longtable’s last column may be much wider than its contents

  • #3507: wrong quotes in latex output for productionlist directive

  • #3533: Moving from Sphinx 1.3.1 to 1.5.3 breaks LaTeX compilation of links rendered as code

  • #2665, #2607: Link names in C++ docfields, and make it possible for other domains.

  • #3542: C++, fix parsing error of non-type template argument with template.

  • #3065, #3520: python domain fails to recognize nested class

  • #3575: Problems with pdflatex in a Turkish document built with Sphinx has reappeared (refs #2997, #2397)

  • #3577: Fix intersphinx debug tool

  • A LaTeX command such as \\large inserted in the title items of latex_documents causes failed PDF build (refs #3551, #3567)

Release 1.5.3 (released Feb 26, 2017)

Features added

  • Support requests-2.0.0 (experimental) (refs: #3367)

  • (latex) PDF page margin dimensions may be customized (refs: #3387)

  • literalinclude directive allows combination of :pyobject: and :lines: options (refs: #3416)

  • #3400: make-mode doesn’t use subprocess on building docs

Bugs fixed

  • #3370: the caption of code-block is not picked up for translation

  • LaTeX: release is not escaped (refs: #3362)

  • #3364: sphinx-quickstart prompts overflow on Console with 80 chars width

  • since 1.5, PDF’s TOC and bookmarks lack an entry for general Index (refs: #3383)

  • #3392: 'releasename' in latex_elements is not working

  • #3356: Page layout for Japanese 'manual' docclass has a shorter text area

  • #3394: When 'pointsize' is not 10pt, Japanese 'manual' document gets wrong PDF page dimensions

  • #3399: quickstart: conf.py was not overwritten by template

  • #3366: option directive does not allow punctuations

  • #3410: return code in release breaks html search

  • #3427: autodoc: memory addresses are not stripped on Windows

  • #3428: xetex build tests fail due to fontspec v2.6 defining \strong

  • #3349: Result of IndexBuilder.load() is broken

  • #3450: &nbsp is appeared in EPUB docs

  • #3418: Search button is misaligned in nature and pyramid theme

  • #3421: Could not translate a caption of tables

  • #3552: linkcheck raises UnboundLocalError

Release 1.5.2 (released Jan 22, 2017)

Incompatible changes

  • Dependency requirement updates: requests 2.4.0 or above (refs: #3268, #3310)

Features added

  • #3241: emit latex warning if buggy titlesec (ref #3210)

  • #3194: Refer the $MAKE environment variable to determine make command

  • Emit warning for nested numbered toctrees (refs: #3142)

  • #978: intersphinx_mapping also allows a list as a parameter

  • #3340: (LaTeX) long lines in parsed-literal are wrapped like in code-block, inline math and footnotes are fully functional.

Bugs fixed

  • #3246: xapian search adapter crashes

  • #3253: In Py2 environment, building another locale with a non-captioned toctree produces None captions

  • #185: References to section title including raw node has broken

  • #3255: In Py3.4 environment, autodoc doesn’t support documentation for attributes of Enum class correctly.

  • #3261: latex_use_parts makes Sphinx crash

  • The warning type misc.highlighting_failure does not work

  • #3294: add_latex_package() make crashes non-LaTeX builders

  • The caption of table are rendered as invalid HTML (refs: #3287)

  • #3268: Sphinx crashes with requests package from Debian jessie

  • #3284: Sphinx crashes on parallel build with an extension which raises unserializable exception

  • #3315: Bibliography crashes on latex build with docclass ‘memoir’

  • #3328: Could not refer rubric implicitly

  • #3329: emit warnings if po file is invalid and can’t read it. Also writing mo

  • #3337: Ugly rendering of definition list term’s classifier

  • #3335: gettext does not extract field_name of a field in a field_list

  • #2952: C++, fix refs to operator() functions.

  • Fix Unicode super- and subscript digits in code-block and parsed-literal LaTeX output (ref #3342)

  • LaTeX writer: leave " character inside parsed-literal as is (ref #3341)

  • #3234: intersphinx failed for encoded inventories

  • #3158: too much space after captions in PDF output

  • #3317: An URL in parsed-literal contents gets wrongly rendered in PDF if with hyphen

  • LaTeX crash if the filename of an image inserted in parsed-literal via a substitution contains an hyphen (ref #3340)

  • LaTeX rendering of inserted footnotes in parsed-literal is wrong (ref #3340)

  • Inline math in parsed-literal is not rendered well by LaTeX (ref #3340)

  • #3308: Parsed-literals don’t wrap very long lines with pdf builder (ref #3340)

  • #3295: Could not import extension sphinx.builders.linkcheck

  • #3285: autosummary: asterisks are escaped twice

  • LaTeX, pass dvipdfm option to geometry package for Japanese documents (ref #3363)

  • Fix parselinenos() could not parse left half open range (cf. “-4”)

Release 1.5.1 (released Dec 13, 2016)

Features added

  • #3214: Allow to suppress “unknown mimetype” warnings from epub builder using suppress_warnings.

Bugs fixed

  • #3195: Can not build in parallel

  • #3198: AttributeError is raised when toctree has ‘self’

  • #3211: Remove untranslated Sphinx locale catalogs (it was covered by untranslated it_IT)

  • #3212: HTML Builders crashes with Docutils 0.13

  • #3207: more latex problems with references inside parsed-literal directive (\DUrole)

  • #3205: sphinx.util.requests crashes with old pyOpenSSL (< 0.14)

  • #3220: KeyError when having a duplicate citation

  • #3200: LaTeX: xref inside desc_name not allowed

  • #3228: build_sphinx command crashes when missing dependency

  • #2469: Ignore updates of catalog files for gettext builder. Thanks to Hiroshi Ohkubo.

  • #3183: Randomized jump box order in generated index page.

Release 1.5 (released Dec 5, 2016)

Incompatible changes

1.5a1

  • latex, package fancybox is not any longer a dependency of sphinx.sty

  • Use 'locales' as a default value of locale_dirs

  • latex, package ifthen is not any longer a dependency of sphinx.sty

  • latex, style file does not modify fancyvrb’s Verbatim (also available as OriginalVerbatim) but uses sphinxVerbatim for name of custom wrapper.

  • latex, package newfloat is not used (and not included) anymore (ref #2660; it was used since 1.3.4 and shipped with Sphinx since 1.4).

  • latex, literal blocks in tables do not use OriginalVerbatim but sphinxVerbatimintable which handles captions and wraps lines (ref #2704).

  • latex, replace pt by TeX equivalent bp if found in width or height attribute of an image.

  • latex, if width or height attribute of an image is given with no unit, use px rather than ignore it.

  • latex: Separate stylesheets of pygments to independent .sty file

  • #2454: The filename of sourcelink is now changed. The value of html_sourcelink_suffix will be appended to the original filename (like index.rst.txt).

  • sphinx.util.copy_static_entry() is now deprecated. Use sphinx.util.fileutil.copy_asset() instead.

  • sphinx.util.osutil.filecopy() skips copying if the file has not been changed (ref: #2510, #2753)

  • Internet Explorer 6-8, Opera 12.1x or Safari 5.1+ support is dropped because jQuery version is updated from 1.11.0 to 3.1.0 (ref: #2634, #2773)

  • QtHelpBuilder doesn’t generate search page (ref: #2352)

  • QtHelpBuilder uses nonav theme instead of default one to improve readability.

  • latex: To provide good default settings to Japanese documents, Sphinx uses jreport and jsbook as docclass if language is ja.

  • sphinx-quickstart now allows a project version is empty

  • Fix :download: role on epub/qthelp builder. They ignore the role because they don’t support it.

  • sphinx.ext.viewcode doesn’t work on epub building by default. viewcode_enable_epub option

  • sphinx.ext.viewcode disabled on singlehtml builder.

  • Use make-mode of sphinx-quickstart by default. To disable this, use -M option

  • Fix genindex.html, Sphinx’s document template, link address to itself to satisfy xhtml standard.

  • Use epub3 builder by default. And the old epub builder is renamed to epub2.

  • Fix epub and epub3 builders that contained links to genindex even if epub_use_index = False.

  • html_translator_class is now deprecated. Use set_translator() API instead.

  • Drop python 2.6 and 3.3 support

  • Drop epub3 builder’s epub3_page_progression_direction option (use epub3_writing_mode).

  • #2877: Rename latex_elements['footer'] to latex_elements['atendofbody']

1.5a2

  • #2983: Rename epub3_description and epub3_contributor to epub_description and epub_contributor.

  • Remove themes/basic/defindex.html; no longer used

  • Sphinx does not ship anymore (but still uses) LaTeX style file fncychap

  • #2435: Slim down quickstarted conf.py

  • The sphinx.sty latex package does not load itself “hyperref”, as this is done later in the preamble of the latex output via 'hyperref' key.

  • Sphinx does not ship anymore a custom modified LaTeX style file tabulary. The non-modified package is used.

  • #3057: By default, footnote marks in latex PDF output are not preceded by a space anymore, \sphinxBeforeFootnote allows user customization if needed.

  • LaTeX target requires that option hyperfootnotes of package hyperref be left unchanged to its default (i.e. true) (refs: #3022)

1.5 final

  • #2986: themes/basic/defindex.html is now deprecated

  • Emit warnings that will be deprecated in Sphinx 1.6 by default. Users can change the behavior by setting the environment variable PYTHONWARNINGS. Please refer Deprecation Warnings.

  • #2454: new JavaScript variable SOURCELINK_SUFFIX is added

Deprecated

These features are removed in Sphinx 1.6:

  • LDML format support in i18n feature

  • sphinx.addnodes.termsep

  • Some functions and classes in sphinx.util.pycompat: zip_longest, product, all, any, next, open, class_types, base_exception, relpath, StringIO, BytesIO. Please use the standard library version instead;

If any deprecation warning like RemovedInSphinxXXXWarning are displayed, please refer Deprecation Warnings.

Features added

1.5a1

  • #2951: Add --implicit-namespaces PEP-0420 support to apidoc.

  • Add :caption: option for sphinx.ext.inheritance_diagram.

  • #2471: Add config variable for default doctest flags.

  • Convert linkcheck builder to requests for better encoding handling

  • #2463, #2516: Add keywords of “meta” directive to search index

  • :maxdepth: option of toctree affects secnumdepth (ref: #2547)

  • #2575: Now sphinx.ext.graphviz allows :align: option

  • Show warnings if unknown key is specified to latex_elements

  • Show warnings if no domains match with primary_domain (ref: #2001)

  • C++, show warnings when the kind of role is misleading for the kind of target it refers to (e.g., using the class role for a function).

  • latex, writer abstracts more of text styling into customizable macros, e.g. the visit_emphasis will output \sphinxstyleemphasis rather than \emph (which may be in use elsewhere or in an added LaTeX package). See list at end of sphinx.sty (ref: #2686)

  • latex, public names for environments and parameters used by note, warning, and other admonition types, allowing full customizability from the 'preamble' key or an input file (ref: feature request #2674, #2685)

  • latex, better computes column widths of some tables (as a result, there will be slight changes as tables now correctly fill the line width; ref: #2708)

  • latex, sphinxVerbatim environment is more easily customizable (ref: #2704). In addition to already existing VerbatimColor and VerbatimBorderColor:

    • two lengths \sphinxverbatimsep and \sphinxverbatimborder,

    • booleans \ifsphinxverbatimwithframe and \ifsphinxverbatimwrapslines.

  • latex, captions for literal blocks inside tables are handled, and long code lines wrapped to fit table cell (ref: #2704)

  • #2597: Show warning messages as darkred

  • latex, allow image dimensions using px unit (default is 96px=1in)

  • Show warnings if invalid dimension units found

  • #2650: Add --pdb option to setup.py command

  • latex, make the use of \small for code listings customizable (ref #2721)

  • #2663: Add --warning-is-error option to setup.py command

  • Show warnings if deprecated latex options are used

  • Add sphinx.config.ENUM to check the config values is in candidates

  • math: Add hyperlink marker to each equations in HTML output

  • Add new theme nonav that doesn’t include any navigation links. This is for any help generator like qthelp.

  • #2680: sphinx.ext.todo now emits warnings if todo_emit_warnings enabled. Also, it emits an additional event named todo-defined to handle the TODO entries in 3rd party extensions.

  • Python domain signature parser now uses the xref mixin for ‘exceptions’, allowing exception classes to be autolinked.

  • #2513: Add latex_engine to switch the LaTeX engine by conf.py

  • #2682: C++, basic support for attributes (C++11 style and GNU style). The new configuration variables ‘cpp_id_attributes’ and ‘cpp_paren_attributes’ can be used to introduce custom attributes.

  • #1958: C++, add configuration variable ‘cpp_index_common_prefix’ for removing prefixes from the index text of C++ objects.

  • C++, added concept directive. Thanks to mickk-on-cpp.

  • C++, added support for template introduction syntax. Thanks to mickk-on-cpp.

  • #2725: latex builder: allow to use user-defined template file (experimental)

  • apidoc now avoids invalidating cached files by not writing to files whose content doesn’t change. This can lead to significant performance wins if apidoc is run frequently.

  • #2851: sphinx.ext.math emits missing-reference event if equation not found

  • #1210: eqref role now supports cross reference

  • #2892: Added -a (--append-syspath) option to sphinx-apidoc

  • #1604: epub3 builder: Obey font-related CSS when viewing in iBooks.

  • #646: option directive support ‘.’ character as a part of options

  • Add document about kindlegen and fix document structure for it.

  • #2474: Add intersphinx_timeout option to sphinx.ext.intersphinx

  • #2926: EPUB3 builder supports vertical mode (epub3_writing_mode option)

  • #2695: build_sphinx subcommand for setuptools handles exceptions as same as sphinx-build does

  • #326: numref role can also refer sections

  • #2916: numref role can also refer caption as an its linktext

1.5a2

  • #3008: linkcheck builder ignores self-signed certificate URL

  • #3020: new 'geometry' key to latex_elements whose default uses LaTeX style file geometry.sty to set page layout

  • #2843: Add :start-at: and :end-at: options to literalinclude directive

  • #2527: Add :reversed: option to toctree directive

  • Add -t and -d option to sphinx-quickstart to support templating generated Sphinx project.

  • #3028: Add {path} and {basename} to the format of figure_language_filename

  • new 'hyperref' key in the latex_elements dictionary (ref #3030)

  • #3022: Allow code-blocks in footnotes for LaTeX PDF output

1.5b1

  • #2513: A better default settings for XeLaTeX

  • #3096: 'maxlistdepth' key to work around LaTeX list limitations

  • #3060: autodoc supports documentation for attributes of Enum class. Now autodoc render just the value of Enum attributes instead of Enum attribute representation.

  • Add --extensions to sphinx-quickstart to support enable arbitrary extensions from command line (ref: #2904)

  • #3104, #3122: 'sphinxsetup' for key=value styling of Sphinx LaTeX

  • #3071: Autodoc: Allow mocked module decorators to pass-through functions unchanged

  • #2495: linkcheck: Allow skipping anchor checking using linkcheck_anchors_ignore

  • #3083: let Unicode no-break space act like LaTeX ~ (fixed #3019)

  • #3116: allow word wrap in PDF output for inline literals (ref #3110)

  • #930: sphinx-apidoc allow wildcards for excluding paths. Thanks to Nick Coghlan.

  • #3121: add inlineliteralwraps option to control if inline literal word-wraps in latex

1.5 final

  • #3095: Add tls_verify and tls_cacerts to support self-signed HTTPS servers in linkcheck and intersphinx

  • #2215: make.bat generated by sphinx-quickstart can be called from another dir. Thanks to Timotheus Kampik.

  • #3185: Add new warning type misc.highlighting_failure

Bugs fixed

1.5a1

  • #2707: (latex) the column width is badly computed for tabular

  • #2799: Sphinx installs roles and directives automatically on importing sphinx module. Now Sphinx installs them on running application.

  • sphinx.ext.autodoc crashes if target code imports * from mock modules by autodoc_mock_imports.

  • #1953: Sphinx.add_node does not add handlers the translator installed by html_translator_class

  • #1797: text builder inserts blank line on top

  • #2894: quickstart main() doesn’t use argv argument

  • #2874: gettext builder could not extract all text under the only directives

  • #2485: autosummary crashes with multiple source_suffix values

  • #1734: Could not translate the caption of toctree directive

  • Could not translate the content of meta directive (ref: #1734)

  • #2550: external links are opened in help viewer

  • #2687: Running Sphinx multiple times produces ‘already registered’ warnings

1.5a2

  • #2810: Problems with pdflatex in an Italian document

  • Use latex_elements.papersize to specify papersize of LaTeX in Makefile

  • #2988: linkcheck: retry with GET request if denied HEAD request

  • #2990: linkcheck raises “Can’t convert ‘bytes’ object to str implicitly” error if linkcheck_anchors enabled

  • #3004: Invalid link types “top” and “up” are used

  • #3009: Bad rendering of parsed-literals in LaTeX since Sphinx 1.4.4

  • #3000: option directive generates invalid HTML anchors

  • #2984: Invalid HTML has been generated if html_split_index enabled

  • #2986: themes/basic/defindex.html should be changed for html5 friendly

  • #2987: Invalid HTML has been generated if multiple IDs are assigned to a list

  • #2891: HTML search does not provide all the results

  • #1986: Title in PDF Output

  • #147: Problem with latex chapter style

  • #3018: LaTeX problem with page layout dimensions and chapter titles

  • Fix an issue with \pysigline in LaTeX style file (ref #3023)

  • #3038: sphinx.ext.math* raises TypeError if labels are duplicated

  • #3031: incompatibility with LaTeX package tocloft

  • #3003: literal blocks in footnotes are not supported by Latex

  • #3047: spacing before footnote in pdf output is not coherent and allows breaks

  • #3045: HTML search index creator should ignore “raw” content if now html

  • #3039: English stemmer returns wrong word if the word is capitalized

  • Fix make-mode Makefile template (ref #3056, #2936)

1.5b1

  • #2432: Fix unwanted * between varargs and keyword only args. Thanks to Alex Grönholm.

  • #3062: Failed to build PDF using 1.5a2 (undefined \hypersetup for Japanese documents since PR#3030)

  • Better rendering of multiline signatures in html.

  • #777: LaTeX output “too deeply nested” (ref #3096)

  • Let LaTeX image inclusion obey scale before textwidth fit (ref #2865, #3059)

  • #3019: LaTeX fails on description of C function with arguments (ref #3083)

  • fix latex inline literals where < > - gobbled a space

1.5 final

  • #3069: Even if 'babel' key is set to empty string, LaTeX output contains one \addto\captions...

  • #3123: user 'babel' key setting is not obeyed anymore

  • #3155: Fix JavaScript for html_sourcelink_suffix fails with IE and Opera

  • #3085: keep current directory after breaking build documentation. Thanks to Timotheus Kampik.

  • #3181: pLaTeX crashes with a section contains endash

  • #3180: latex: add stretch/shrink between successive singleline or multipleline cpp signatures (ref #3072)

  • #3128: globing images does not support .svgz file

  • #3015: fix a broken test on Windows.

  • #1843: Fix documentation of descriptor classes that have a custom metaclass. Thanks to Erik Bray.

  • #3190: util.split_docinfo fails to parse multi-line field bodies

  • #3024, #3037: In Python3, application.Sphinx._log crushed when the log message cannot be encoded into console encoding.

Testing

  • To simplify, Sphinx uses external mock package even if unittest.mock exists.