Sphinx

=====================================

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] :file:`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 :confval:`latex_engine`
* 4090: [doc] :confval:`latex_additional_files` with extra LaTeX macros should
not use ``.tex`` extension
* Failed to convert reST parser error to warning (refs: 4132)

=====================================

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

=====================================

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

=====================================

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 <https://readthedocs.org/>`_ PDF builds of Sphinx own docs are
missing an index entry in the bookmarks and table of contents. This is
`rtfd/readthedocs.org2857
<https://github.com/rtfd/readthedocs.org/issues/2857>`_ issue, a workaround
is obtained using some extra LaTeX code in Sphinx's own :file:`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

=====================================

Dependencies
------------

* 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 :ref:`when-deprecation-warnings-are-displayed`.

Features added
--------------