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 弃用警告.

• #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 弃用警告.

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.

Previous

Sphinx 1.6

Next

Sphinx 1.4