Sphinx 1.6¶

Release 1.6.7 (released Feb 04, 2018)¶

Bugs fixed¶

• #1922: html search: Upper characters problem in French

• #4412: Updated jQuery version from 3.1.0 to 3.2.1

• #4438: math: math with labels with whitespace cause html error

• #2437: make full reference for classes, aliased with "alias of"

• #4434: pure numbers as link targets produce warning

• #4477: Build fails after building specific files

• #4449: apidoc: include "empty" packages that contain modules

• #3917: citation labels are transformed to ellipsis

• #4501: graphviz: epub3 validation error caused if graph is not clickable

• #4514: graphviz: workaround for wrong map ID which graphviz generates

• #4525: autosectionlabel does not support parallel build

• #3953: Do not raise warning when there is a working intersphinx inventory

• #4487: math: ValueError is raised on parallel build. Thanks to jschueller.

• #2372: autosummary: invalid signatures are shown for type annotated functions

• #3942: html: table is not aligned to center even if :align: center

Release 1.6.6 (released Jan 08, 2018)¶

Features added¶

• #4181: autodoc: Sort dictionary keys when possible

• VerbatimHighlightColor is a new LaTeX ‘sphinxsetup’ key (refs: #4285)

• Easier customizability of LaTeX macros involved in rendering of code-blocks

• Show traceback if conf.py raises an exception (refs: #4369)

• Add smartquotes to disable smart quotes through conf.py (refs: #3967)

• Add smartquotes_action and smartquotes_excludes (refs: #4142, #4357)

Bugs fixed¶

• #4334: sphinx-apidoc: Don’t generate references to non-existing files in TOC

• #4206: latex: reST label between paragraphs loses paragraph break

• #4231: html: Apply fixFirefoxAnchorBug only under Firefox

• #4221: napoleon depends on autodoc, but users need to load it manually

• #2298: automodule fails to document a class attribute

• #4099: C++: properly link class reference to class from inside constructor

• #4267: PDF build broken by Unicode U+2116 NUMERO SIGN character

• #4249: PDF output: Pygments error highlighting increases line spacing in code blocks

• #1238: Support :emphasize-lines: in PDF output

• #4279: Sphinx crashes with pickling error when run with multiple processes and remote image

• #1421: Respect the quiet flag in sphinx-quickstart

• #4281: Race conditions when creating output directory

• #4315: For PDF ‘howto’ documents, latex_toplevel_sectioning='part' generates \chapter commands

• #4214: Two todolist directives break Sphinx 1.6.5

• Fix links to external option docs with intersphinx (refs: #3769)

• #4091: Private members not documented without :undoc-members:

Release 1.6.5 (released Oct 23, 2017)¶

Features added¶

• #4107: Make searchtools.js compatible with pre-Sphinx1.5 templates

• #4112: Don’t override the smart_quotes setting if it was already set

• #4125: Display reference texts of original and translated passages on i18n warning message

• #4147: Include the exception when logging PO/MO file read/write

Bugs fixed¶

• #4085: Failed PDF build from image in parsed-literal using :align: option

• #4100: Remove debug print from autodoc extension

• #3987: Changing theme from alabaster causes HTML build to fail

• #4096: C++, don’t crash when using the wrong role type. Thanks to mitya57.

• #4070, #4111: crashes when the warning message contains format strings (again)

• #4108: Search word highlighting breaks SVG images

• #3692: Unable to build HTML if writing .buildinfo failed

• #4152: HTML writer crashes if a field list is placed on top of the document

• #4063: Sphinx crashes when labeling directive .. todolist::

• #4134: [doc] docutils.conf is not documented explicitly

• #4169: Chinese language doesn’t trigger Chinese search automatically

• #1020: ext.todo todolist not linking to the page in pdflatex

• #3965: New quickstart generates wrong SPHINXBUILD in Makefile

• #3739: :module: option is ignored at content of pyobjects

• #4149: Documentation: Help choosing latex_engine

• #4090: [doc] latex_additional_files with extra LaTeX macros should not use .tex extension

• Failed to convert reST parser error to warning (refs: #4132)

Release 1.6.4 (released Sep 26, 2017)¶

Features added¶

• #3926: Add autodoc_warningiserror to suppress the behavior of -W option during importing target modules on autodoc

Bugs fixed¶

• #3924: docname lost after dynamically parsing RST in extension

• #3946: Typo in sphinx.sty (this was a bug with no effect in default context)

• pep:

  and :rfc: does not supports default-role directive (refs: #3960)

• #3960: default_role = ‘guilabel’ not functioning

• Missing texinputs_win/Makefile to be used in latexpdf builder on windows.

• #4026: nature: Fix macOS Safari scrollbar color

• #3877: Fix for C++ multiline signatures.

• #4006: Fix crash on parallel build

• #3969: private instance attributes causes AttributeError

• #4041: C++, remove extra name linking in function pointers.

• #4038: C, add missing documentation of member role.

• #4044: An empty multicolumn cell causes extra row height in PDF output

• #4049: Fix typo in output of sphinx-build -h

• #4062: hashlib.sha1() must take bytes, not unicode on Python 3

• Avoid indent after index entries in latex (refs: #4066)

• #4070: crashes when the warning message contains format strings

• #4067: Return non-zero exit status when make subprocess fails

• #4055: graphviz: the :align: option does not work for SVG output

• #4055: graphviz: the :align: center option does not work for latex output

• #4051: warn() function for HTML theme outputs ‘None’ string

Release 1.6.3 (released Jul 02, 2017)¶

Features added¶

• latex: hint that code-block continues on next page (refs: #3764, #3792)

Bugs fixed¶

• #3821: Failed to import sphinx.util.compat with Docutils 0.14rc1

• #3829: sphinx-quickstart template is incomplete regarding use of alabaster

• #3772: ‘str object’ has no attribute ‘filename’

• Emit wrong warnings if citation label includes hyphens (refs: #3565)

• #3858: Some warnings are not colored when using –color option

• #3775: Remove unwanted whitespace in default template

• #3835: sphinx.ext.imgmath fails to convert SVG images if project directory name contains spaces

• #3850: Fix color handling in make mode’s help command

• #3865: use of self.env.warn in Sphinx extension fails

• #3824: production lists apply smart quotes transform since Sphinx 1.6.1

• latex: fix \sphinxbfcode swallows initial space of argument

• #3878: Quotes in auto-documented class attributes should be straight quotes in PDF output

• #3881: LaTeX figure floated to next page sometimes leaves extra vertical whitespace

• #3885: duplicated footnotes raises IndexError

• #3873: Failure of deprecation warning mechanism of sphinx.util.compat.Directive

• #3874: Bogus warnings for "citation not referenced" for cross-file citations

• #3860: Don’t download images when builders not supported images

• #3860: Remote image URIs without filename break builders not supported remote images

• #3833: command line messages are translated unintentionally with language setting.

• #3840: make checking epub_uid strict

• #3851, #3706: Fix about box drawing characters for PDF output

• #3900: autosummary could not find methods

• #3902: Emit error if latex_documents contains non-unicode string in py2

Release 1.6.2 (released May 28, 2017)¶

Incompatible changes¶

• #3789: Do not require typing module for python>=3.5

Bugs fixed¶

• #3754: HTML builder crashes if HTML theme appends own stylesheets

• #3756: epub: Entity ‘mdash’ not defined

• #3758: Sphinx crashed if logs are emitted in conf.py

• #3755: incorrectly warns about dedent with literalinclude

• #3742: RTD PDF builds of Sphinx own docs are missing an index entry in the bookmarks and table of contents. This is rtfd/readthedocs.org#2857 issue, a workaround is obtained using some extra LaTeX code in Sphinx’s own conf.py

• #3770: Build fails when a "code-block" has the option emphasize-lines and the number indicated is higher than the number of lines

• #3774: Incremental HTML building broken when using citations

• #3763: got epubcheck validations error if epub_cover is set

• #3779: ‘ImportError’ in sphinx.ext.autodoc due to broken ‘sys.meta_path’. Thanks to Tatiana Tereshchenko.

• #3796: env.resolve_references() crashes when non-document node given

• #3803: Sphinx crashes with invalid PO files

• #3791: PDF "continued on next page" for long tables isn’t internationalized

• #3788: smartquotes emits warnings for unsupported languages

• #3807: latex Makefile for make latexpdf is only for unixen

• #3781: double hyphens in option directive are compiled as endashes

• #3817: latex builder raises AttributeError

Release 1.6.1 (released May 16, 2017)¶

Dependencies¶

1.6b1

• (updated) latex output is tested with Ubuntu trusty’s texlive packages (Feb. 2014) and earlier tex installations may not be fully compliant, particularly regarding Unicode engines xelatex and lualatex

• (added) latexmk is required for make latexpdf on GNU/Linux and Mac OS X (refs: #3082)

Incompatible changes¶

1.6b1

• #1061, #2336, #3235: Now generation of autosummary doesn’t contain imported members by default. Thanks to Luc Saffre.

• LaTeX \includegraphics command isn’t overloaded: only \sphinxincludegraphics has the custom code to fit image to available width if oversized.

• The subclasses of sphinx.domains.Index should override generate() method. The default implementation raises NotImplementedError

• LaTeX positioned long tables horizontally centered, and short ones flushed left (no text flow around table.) The position now defaults to center in both cases, and it will obey Docutils 0.13 :align: option (refs #3415, #3377)

• option directive also allows all punctuations for the option name (refs: #3366)

• #3413: if literalinclude’s :start-after: is used, make :lines: relative (refs #3412)

• literalinclude directive does not allow the combination of :diff: option and other options (refs: #3416)

• LuaLaTeX engine uses fontspec like XeLaTeX. It is advised latex_engine = 'lualatex' be used only on up-to-date TeX installs (refs #3070, #3466)

• latex_keep_old_macro_names default value has been changed from True to False. This means that some LaTeX macros for styling are by default defined only with \sphinx.. prefixed names. (refs: #3429)

• Footer "Continued on next page" of LaTeX longtable’s now not framed (refs: #3497)

• #3529: The arguments of BuildEnvironment.__init__ is changed

• #3082: Use latexmk for pdf (and dvi) targets (Unix-like platforms only)

• #3558: Emit warnings if footnotes and citations are not referenced. The warnings can be suppressed by suppress_warnings.

• latex made available (non documented) colour macros from a file distributed with pdftex engine for Plain TeX. This is removed in order to provide better support for multiple TeX engines. Only interface from color or xcolor packages should be used by extensions of Sphinx latex writer. (refs #3550)

• Builder.env is not filled at instantiation

• #3594: LaTeX: single raw directive has been considered as block level element

• #3639: If html_experimental_html5_writer is available, epub builder use it by default.

• Sphinx.add_source_parser() raises an error if duplicated

1.6b2

• #3345: Replace the custom smartypants code with Docutils’ smart_quotes. Thanks to Dmitry Shachnev, and to Günter Milde at Docutils.

1.6b3

• LaTeX package eqparbox is not used and not loaded by Sphinx anymore

• LaTeX package multirow is not used and not loaded by Sphinx anymore

• Add line numbers to citation data in std domain

1.6 final

• LaTeX package threeparttable is not used and not loaded by Sphinx anymore (refs #3686, #3532, #3377)

Features removed¶

• Configuration variables

  • epub3_contributor

  • epub3_description

  • epub3_page_progression_direction

  • html_translator_class

  • html_use_modindex

  • latex_font_size

  • latex_paper_size

  • latex_preamble

  • latex_use_modindex

  • latex_use_parts

• termsep node

• defindex.html template

• LDML format support in today, today_fmt and html_last_updated_fmt

• :inline: option for the directives of sphinx.ext.graphviz extension

• sphinx.ext.pngmath extension

• sphinx.util.compat.make_admonition()

Features added¶

1.6b1

• #3136: Add :name: option to the directives in sphinx.ext.graphviz

• #2336: Add imported_members option to sphinx-autogen command to document imported members.

• C++, add :tparam-line-spec: option to templated declarations. When specified, each template parameter will be rendered on a separate line.

• #3359: Allow sphinx.js in a user locale dir to override sphinx.js from Sphinx

• #3303: Add :pyversion: option to the doctest directive.

• #3378: (latex) support for :widths: option of table directives (refs: #3379, #3381)

• #3402: Allow to suppress "download file not readable" warnings using suppress_warnings.

• #3377: latex: Add support for Docutils 0.13 :align: option for tables (but does not implement text flow around table).

• latex: footnotes from inside tables are hyperlinked (except from captions or headers) (refs: #3422)

• Emit warning if over dedent has detected on literalinclude directive (refs: #3416)

• Use for LuaLaTeX same default settings as for XeLaTeX (i.e. fontspec and polyglossia). (refs: #3070, #3466)

• Make 'extraclassoptions' key of latex_elements public (refs #3480)

• #3463: Add warning messages for required EPUB3 metadata. Add default value to epub_description to avoid warning like other settings.

• #3476: setuptools: Support multiple builders

• latex: merged cells in LaTeX tables allow code-blocks, lists, blockquotes... as do normal cells (refs: #3435)

• HTML builder uses experimental HTML5 writer if html_experimental_html5_writer is True and Docutils 0.13 or later is installed.

• LaTeX macros to customize space before and after tables in PDF output (refs #3504)

• #3348: Show decorators in literalinclude and viewcode directives

• #3108: Show warning if :start-at: and other literalinclude options does not match to the text

• #3609: Allow to suppress "duplicate citation" warnings using suppress_warnings

• #2803: Discovery of builders by entry point

• #1764, #1676: Allow setting ‘rel’ and ‘title’ attributes for stylesheets

• #3589: Support remote images on non-HTML builders

• #3589: Support images in Data URI on non-HTML builders

• #2961: improve autodoc_mock_imports. Now the config value only requires to declare the top-level modules that should be mocked. Thanks to Robin Jarry.

• #3449: On py3, autodoc use inspect.signature for more accurate signature calculation. Thanks to Nathaniel J. Smith.

• #3641: Epub theme supports HTML structures that are generated by HTML5 writer.

• #3644: autodoc uses inspect instead of checking types. Thanks to Jeroen Demeyer.

• Add a new extension; sphinx.ext.imgconverter. It converts images in the document to appropriate format for builders

• latex: Use templates to render tables (refs #3389, 2a37b0e)

1.6b2

• LATEXMKOPTS variable for the Makefile in $BUILDDIR/latex to pass options to latexmk when executing make latexpdf (refs #3695, #3720)

• Add a new event env-check-consistency to check consistency to extensions

• Add Domain.check_consistency() to check consistency

Bugs fixed¶

1.6b1

• literalinclude directive expands tabs after dedent-ing (refs: #3416)

• #1574: Paragraphs in table cell doesn’t work in Latex output

• #3288: Table with merged headers not wrapping text

• #3491: Inconsistent vertical space around table and longtable in PDF

• #3506: Depart functions for all admonitions in HTML writer now properly pass node to depart_admonition.

• #2693: Sphinx latex style file wrongly inhibits colours for section headings for latex+dvi(ps,pdf,pdfmx)

• C++, properly look up any references.

• #3624: sphinx.ext.intersphinx couldn’t load inventories compressed with gzip

• #3551: PDF information dictionary is lacking author and title data

• #3351: intersphinx does not refers context like py:module, py:class and so on.

• Fail to load template file if the parent template is archived

1.6b2

• #3661: sphinx-build crashes on parallel build

• #3669: gettext builder fails with "ValueError: substring not found"

• #3660: Sphinx always depends on sphinxcontrib-websupport and its dependencies

• #3472: smart quotes getting wrong in latex (at least with list of strings via autoattribute) (refs: #3345, #3666)

1.6b3

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

• The make latexpdf from 1.6b1 (for GNU/Linux and Mac OS, using latexmk) aborted earlier in case of LaTeX errors than was the case with 1.5 series, due to hard-coded usage of --halt-on-error option (refs #3695)

• #3683: sphinx.websupport module is not provided by default

• #3683: Failed to build document if builder.css_file.insert() is called

• #3714: viewcode extension not taking highlight_code='none' in account

• #3698: Moving :doc: to std domain broke backwards compatibility

• #3633: misdetect unreferenced citations

1.6 final

• LaTeX tables do not allow multiple paragraphs in a header cell

• LATEXOPTS is not passed over correctly to pdflatex since 1.6b3

• #3532: Figure or literal block captions in cells of short tables cause havoc in PDF output

• Fix: in PDF captions of tables are rendered differently whether table is of longtable class or not (refs #3686)

• #3725: Todo looks different from note in LaTeX output

• #3479: stub-columns have no effect in LaTeX output

• #3738: Nonsensical code in theming.py

• #3746: PDF builds fail with latexmk 4.48 or earlier due to undefined options -pdfxe and -pdflua

Deprecated¶

1.6b1

• sphinx.util.compat.Directive class is now deprecated. Please use instead docutils.parsers.rst.Directive

• sphinx.util.compat.docutils_version is now deprecated

• #2367: Sphinx.warn(), Sphinx.info() and other logging methods are now deprecated. Please use sphinx.util.logging (Logging API) instead.

• #3318: notice is now deprecated as LaTeX environment name and will be removed at Sphinx 1.7. Extension authors please use sphinxadmonition instead (as Sphinx does since 1.5.)

• Sphinx.status_iterator() and Sphinx.old_status_iterator() is now deprecated. Please use sphinx.util:status_iterator() instead.

• Sphinx._directive_helper() is deprecated. Please use sphinx.util.docutils.directive_helper() instead.

• BuildEnvironment.set_warnfunc() is now deprecated

• Following methods of BuildEnvironment is now deprecated.

  • BuildEnvironment.note_toctree()

  • BuildEnvironment.get_toc_for()

  • BuildEnvironment.get_toctree_for()

  • BuildEnvironment.create_index()

  Please use sphinx.environment.adapters modules instead.

• latex package footnote is not loaded anymore by its bundled replacement footnotehyper-sphinx. The redefined macros keep the same names as in the original package.

• #3429: deprecate config setting latex_keep_old_macro_names. It will be removed at 1.7, and already its default value has changed from True to False.

• #3221: epub2 builder is deprecated

• #3254: sphinx.websupport is now separated into independent package; sphinxcontrib-websupport. sphinx.websupport will be removed in Sphinx 2.0.

• #3628: sphinx_themes entry_point is deprecated. Please use sphinx.html_themes instead.

1.6b2

• #3662: builder.css_files is deprecated. Please use add_stylesheet() API instead.

1.6 final

• LaTeX \sphinxstylethead is deprecated at 1.6 and will be removed at 1.7. Please move customization into new macro \sphinxstyletheadfamily.

Testing¶

1.6 final

• #3458: Add sphinx.testing (experimental)

Release 1.6 (unreleased)¶

• not released (because of package script error)

Previous

Sphinx 1.7

Next

Sphinx 1.5