Release 3.1.0 (in development)

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

Dependencies

------------

Incompatible changes

--------------------

* #7477: imgconverter: Invoke "magick convert" command by default on Windows

Deprecated

----------

* The ``module`` argument of ``sphinx.ext.autosummary.generate.

find_autosummary_in_docstring()``

Features added

--------------

* LaTeX: Make the ``toplevel_sectioning`` setting optional in LaTeX theme

* #7410: Allow to suppress "circular toctree references detected" warnings using

:confval:`suppress_warnings`

* C, added scope control directives, :rst:dir:`c:namespace`,

:rst:dir:`c:namespace-push`, and :rst:dir:`c:namespace-pop`.

* #7466: autosummary: headings in generated documents are not translated

* #7481: html theme: Add right margin to footnote/citation labels

* #7482: html theme: CSS spacing for code blocks with captions and line numbers

Bugs fixed

----------

Testing

--------

Release 3.0.2 (in development)

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

Dependencies

------------

Incompatible changes

--------------------

Deprecated

----------

Features added

--------------

* C, parse attributes and add :confval:`c_id_attributes`

and :confval:`c_paren_attributes` to support user-defined attributes.

Bugs fixed

----------

* #7461: py domain: fails with IndexError for empty tuple in type annotation

* #7461: autodoc: empty tuple in type annotation is not shown correctly

Testing

--------

Release 3.0.1 (released Apr 11, 2020)

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

Incompatible changes

--------------------

* #7418: std domain: :rst:dir:`term` role becomes case sensitive

Bugs fixed

----------

* #7428: py domain: a reference to class ``None`` emits a nitpicky warning

* #7445: py domain: a return annotation ``None`` in the function signature is

not converted to a hyperlink when using intersphinx

* #7418: std domain: duplication warning for glossary terms is case insensitive

* #7438: C++, fix merging overloaded functions in parallel builds.

* #7422: autodoc: fails with ValueError when using autodoc_mock_imports

* #7435: autodoc: ``autodoc_typehints='description'`` doesn't suppress typehints

in signature for classes/methods

* #7451: autodoc: fails with AttributeError when an object returns non-string

object as a ``__doc__`` member

* #7423: crashed when giving a non-string object to logger

* #7479: html theme: Do not include xmlns attribute with HTML 5 doctype

* #7426: html theme: Escape some links in HTML templates

Release 3.0.0 (released Apr 06, 2020)

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

Dependencies

------------

3.0.0b1

* LaTeX: drop dependency on :program:`extractbb` for image inclusion in

Japanese documents as ``.xbb`` files are unneeded by :program:`dvipdfmx`

since TeXLive2015 (refs: #6189)

* babel-2.0 or above is available (Unpinned)

Incompatible changes

--------------------

3.0.0b1

* Drop features and APIs deprecated in 1.8.x

* #247: autosummary: stub files are overwritten automatically by default. see

:confval:`autosummary_generate_overwrite` to change the behavior

* #5923: autodoc: the members of ``object`` class are not documented by default

when ``:inherited-members:`` and ``:special-members:`` are given.

* #6830: py domain: ``meta`` fields in info-field-list becomes reserved. They

are not displayed on output document now

* #6417: py domain: doctree of desc_parameterlist has been changed. The

argument names, annotations and default values are wrapped with inline node

* The structure of ``sphinx.events.EventManager.listeners`` has changed

* Due to the scoping changes for :rst:dir:`productionlist` some uses of

:rst:role:`token` must be modified to include the scope which was previously

ignored.

* #6903: Internal data structure of Python, reST and standard domains have

changed. The node_id is added to the index of objects and modules. Now they

contains a pair of docname and node_id for cross reference.

* #7276: C++ domain: Non intended behavior is removed such as ``say_hello_``

links to ``.. cpp:function:: say_hello()``

* #7210: js domain: Non intended behavior is removed such as ``parseInt_`` links

to ``.. js:function:: parseInt``

* #7229: rst domain: Non intended behavior is removed such as ``numref_`` links

to ``.. rst:role:: numref``

* #6903: py domain: Non intended behavior is removed such as ``say_hello_``

links to ``.. py:function:: say_hello()``

* #7246: py domain: Drop special cross reference helper for exceptions,

functions and methods

* The C domain has been rewritten, with additional directives and roles.

The existing ones are now more strict, resulting in new warnings.

* The attribute ``sphinx_cpp_tagname`` in the ``desc_signature_line`` node

has been renamed to ``sphinx_line_type``.

* #6462: double backslashes in domain directives are no longer replaced by

single backslashes as default. A new configuration value

:confval:`strip_signature_backslash` can be used by users to reenable it.

3.0.0 final

* #7222: ``sphinx.util.inspect.unwrap()`` is renamed to ``unwrap_all()``

Deprecated

----------

3.0.0b1

* ``desc_signature['first']``

* ``sphinx.directives.DescDirective``

* ``sphinx.domains.std.StandardDomain.add_object()``

* ``sphinx.domains.python.PyDecoratorMixin``

* ``sphinx.ext.autodoc.get_documenters()``

* ``sphinx.ext.autosummary.process_autosummary_toc()``

* ``sphinx.parsers.Parser.app``

* ``sphinx.testing.path.Path.text()``

* ``sphinx.testing.path.Path.bytes()``

* ``sphinx.util.inspect.getargspec()``

* ``sphinx.writers.latex.LaTeXWriter.format_docclass()``

Features added

--------------

3.0.0b1

* #247: autosummary: Add :confval:`autosummary_generate_overwrite` to overwrite

old stub file

* #5923: autodoc: ``:inherited-members:`` option takes a name of anchestor class

not to document inherited members of the class and uppers

* #6830: autodoc: consider a member private if docstring contains

``:meta private:`` in info-field-list

* #7165: autodoc: Support Annotated type (PEP-593)

* #2815: autodoc: Support singledispatch functions and methods

* #7079: autodoc: :confval:`autodoc_typehints` accepts ``"description"``

configuration. It shows typehints as object description

* #7314: apidoc: Propagate ``--maxdepth`` option through package documents

* #6558: glossary: emit a warning for duplicated glossary entry

* #3106: domain: Register hyperlink target for index page automatically

* #6558: std domain: emit a warning for duplicated generic objects

* #6830: py domain: Add new event: :event:`object-description-transform`

* #6895: py domain: Do not emit nitpicky warnings for built-in types

* py domain: Support lambda functions in function signature

* #6417: py domain: Allow to make a style for arguments of functions and methods

* #7238, #7239: py domain: Emit a warning on describing a python object if the

entry is already added as the same name

* #7341: py domain: type annotations in singature are converted to cross refs

* Support priority of event handlers. For more detail, see

:py:meth:`.Sphinx.connect()`

* #3077: Implement the scoping for :rst:dir:`productionlist` as indicated

in the documentation.

* #1027: Support backslash line continuation in :rst:dir:`productionlist`.

* #7108: config: Allow to show an error message from conf.py via ``ConfigError``

* #7032: html: :confval:`html_scaled_image_link` will be disabled for images having

``no-scaled-link`` class

* #7144: Add CSS class indicating its domain for each desc node

* #7211: latex: Use babel for Chinese document when using XeLaTeX

* #6672: LaTeX: Support LaTeX Theming (experimental)

* #7005: LaTeX: Add LaTeX styling macro for :rst:role:`kbd` role

* #7220: genindex: Show "main" index entries at first

* #7103: linkcheck: writes all links to ``output.json``

* #7025: html search: full text search can be disabled for individual document

using ``:nosearch:`` file-wide metadata

* #7293: html search: Allow to override JavaScript splitter via

``SearchLanguage.js_splitter_code``

* #7142: html theme: Add a theme option: ``pygments_dark_style`` to switch the

style of code-blocks in dark mode

* The C domain has been rewritten adding for example:

- Cross-referencing respecting the current scope.

- Possible to document anonymous entities.

- More specific directives and roles for each type of entitiy,

e.g., handling scoping of enumerators.

- New role :rst:role:`c:expr` for rendering expressions and types

in text.

* Added ``SphinxDirective.get_source_info()``

and ``SphinxRole.get_source_info()``.

* #7324: sphinx-build: Emit a warning if multiple files having different file

extensions for same document found

3.0.0 final

* Added ``ObjectDescription.transform_content()``.

Bugs fixed

----------

3.0.0b1

* C++, fix cross reference lookup in certain cases involving

function overloads.

* #5078: C++, fix cross reference lookup when a directive contains multiple

declarations.

* C++, suppress warnings for directly dependent typenames in cross references

generated automatically in signatures.

* #5637: autodoc: Incorrect handling of nested class names on show-inheritance

* #7267: autodoc: error message for invalid directive options has wrong location

* #7329: autodoc: info-field-list is wrongly generated from type hints into the

class description even if ``autoclass_content='class'`` set

* #7331: autodoc: a cython-function is not recognized as a function

* #5637: inheritance_diagram: Incorrect handling of nested class names

* #7139: ``code-block:: guess`` does not work

* #7325: html: source_suffix containing dot leads to wrong source link

* #7357: html: Resizing SVG image fails with ValueError

* #7278: html search: Fix use of ``html_file_suffix`` instead of

``html_link_suffix`` in search results

* #7297: html theme: ``bizstyle`` does not support ``sidebarwidth``

* #3842: singlehtml: Path to images broken when master doc is not in source root

* #7179: std domain: Fix whitespaces are suppressed on referring GenericObject

* #7289: console: use bright colors instead of bold

* #1539: C, parse array types.

* #2377: C, parse function pointers even in complex types.

* #7345: sphinx-build: Sphinx crashes if output directory exists as a file

* #7290: sphinx-build: Ignore bdb.BdbQuit when handling exceptions

* #6240: napoleon: Attributes and Methods sections ignore :noindex: option

3.0.0 final

* #7364: autosummary: crashed when :confval:`autosummary_generate` is False

* #7370: autosummary: raises UnboundLocalError when unknown module given

* #7367: C++, alternate operator spellings are now supported.

* C, alternate operator spellings are now supported.

* #7368: C++, comma operator in expressions, pack expansion in template

argument lists, and more comprehensive error messages in some cases.

* C, C++, fix crash and wrong duplicate warnings related to anon symbols.

* #6477: Escape first "!" in a cross reference linking no longer possible

* #7219: py domain: The index entry generated by ``py:function`` directive is

different with one from ``index`` directive with "builtin" type

* #7301: capital characters are not allowed for node_id

* #7301: epub: duplicated node_ids are generated

* #6564: html: a width of table was ignored on HTML builder

* #7401: Incorrect argument is passed for :event:`env-get-outdated` handlers

* #7355: autodoc: a signature of cython-function is not recognized well

* #7222: autodoc: ``__wrapped__`` functions are not documented correctly

* #7409: intersphinx: ValueError is raised when an extension sets up

:confval:`intersphinx_mapping` on :event:`config-inited` event

* #7343: Sphinx builds has been slower since 2.4.0 on debug mode

Release 2.4.4 (released Mar 05, 2020)

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

Bugs fixed

----------

* #7197: LaTeX: platex cause error to build image directive with target url

* #7223: Sphinx builds has been slower since 2.4.0

Release 2.4.3 (released Feb 22, 2020)

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

Bugs fixed

----------

* #7184: autodoc: ``*args`` and ``**kwarg`` in type comments are not handled

properly

* #7189: autodoc: classmethod coroutines are not detected

* #7183: intersphinx: ``:attr:`` reference to property is broken

* #6244, #6387: html search: Search breaks/hangs when built with dirhtml builder

* #7195: todo: emit doctree-resolved event with non-document node incorrectly

Release 2.4.2 (released Feb 19, 2020)

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

Bugs fixed

----------

* #7138: autodoc: ``autodoc.typehints`` crashed when variable has unbound object

as a value

* #7156: autodoc: separator for keyword only arguments is not shown

* #7146: autodoc: IndexError is raised on suppressed type_comment found

* #7161: autodoc: typehints extension does not support parallel build

* #7178: autodoc: TypeError is raised on fetching type annotations

* #7151: crashed when extension assigns a value to ``env.indexentries``

* #7170: text: Remove debug print

* #7137: viewcode: Avoid to crash when non-python code given

Release 2.4.1 (released Feb 11, 2020)

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

Bugs fixed

----------

* #7120: html: crashed when on scaling SVG images which have float dimentions

* #7126: autodoc: TypeError: 'getset_descriptor' object is not iterable

Release 2.4.0 (released Feb 09, 2020)

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

Deprecated

----------

* The ``decode`` argument of ``sphinx.pycode.ModuleAnalyzer()``

* ``sphinx.directives.other.Index``

* ``sphinx.environment.temp_data['gloss_entries']``

* ``sphinx.environment.BuildEnvironment.indexentries``

* ``sphinx.environment.collectors.indexentries.IndexEntriesCollector``

* ``sphinx.ext.apidoc.INITPY``

* ``sphinx.ext.apidoc.shall_skip()``

* ``sphinx.io.FiletypeNotFoundError``

* ``sphinx.io.get_filetype()``

* ``sphinx.pycode.ModuleAnalyzer.encoding``

* ``sphinx.roles.Index``

* ``sphinx.util.detect_encoding()``

* ``sphinx.util.get_module_source()``

* ``sphinx.util.inspect.Signature``

* ``sphinx.util.inspect.safe_getmembers()``

* ``sphinx.writers.latex.LaTeXTranslator.settings.author``

* ``sphinx.writers.latex.LaTeXTranslator.settings.contentsname``

* ``sphinx.writers.latex.LaTeXTranslator.settings.docclass``

* ``sphinx.writers.latex.LaTeXTranslator.settings.docname``

* ``sphinx.writers.latex.LaTeXTranslator.settings.title``

* ``sphinx.writers.latex.ADDITIONAL_SETTINGS``

* ``sphinx.writers.latex.DEFAULT_SETTINGS``

* ``sphinx.writers.latex.LUALATEX_DEFAULT_FONTPKG``

* ``sphinx.writers.latex.PDFLATEX_DEFAULT_FONTPKG``

* ``sphinx.writers.latex.XELATEX_DEFAULT_FONTPKG``

* ``sphinx.writers.latex.XELATEX_GREEK_DEFAULT_FONTPKG``

Features added

--------------

* #6910: inheritance_diagram: Make the background of diagrams transparent

* #6446: duration: Add ``sphinx.ext.durations`` to inspect which documents slow

down the build

* #6837: LaTeX: Support a nested table

* #7115: LaTeX: Allow to override LATEXOPTS and LATEXMKOPTS via environment

variable

* #6966: graphviz: Support ``:class:`` option

* #6696: html: ``:scale:`` option of image/figure directive not working for SVG

images (imagesize-1.2.0 or above is required)

* #6994: imgconverter: Support illustrator file (.ai) to .png conversion

* autodoc: Support Positional-Only Argument separator (PEP-570 compliant)

* autodoc: Support type annotations for variables

* #2755: autodoc: Add new event: :event:`autodoc-before-process-signature`

* #2755: autodoc: Support type_comment style (ex. ``# type: (str) -> str``)

annotation (python3.8+ or `typed_ast <https://github.com/python/typed_ast>`_

is required)

* #7051: autodoc: Support instance variables without defaults (PEP-526)

* #6418: autodoc: Add a new extension ``sphinx.ext.autodoc.typehints``. It shows

typehints as object description if ``autodoc_typehints = "description"`` set.

This is an experimental extension and it will be integrated into autodoc core

in Sphinx-3.0

* SphinxTranslator now calls visitor/departure method for super node class if

visitor/departure method for original node class not found

* #6418: Add new event: :event:`object-description-transform`

* py domain: :rst:dir:`py:data` and :rst:dir:`py:attribute` take new options

named ``:type:`` and ``:value:`` to describe its type and initial value

* #6785: py domain: ``:py:attr:`` is able to refer properties again

* #6772: apidoc: Add ``-q`` option for quiet mode

Bugs fixed

----------

* #6925: html: Remove redundant type="text/javascript" from <script> elements

* #7112: html: SVG image is not layouted as float even if aligned

* #6906, #6907: autodoc: failed to read the source codes encoeded in cp1251

* #6961: latex: warning for babel shown twice

* #7059: latex: LaTeX compilation falls into infinite loop (wrapfig issue)

* #6581: latex: ``:reversed:`` option for toctree does not effect to LaTeX build

* #6559: Wrong node-ids are generated in glossary directive

* #6986: apidoc: misdetects module name for .so file inside module

* #6899: apidoc: private members are not shown even if ``--private`` given

* #6327: apidoc: Support a python package consisted of __init__.so file

* #6999: napoleon: fails to parse tilde in :exc: role

* #7019: gettext: Absolute path used in message catalogs

* #7023: autodoc: nested partial functions are not listed

* #7023: autodoc: partial functions imported from other modules are listed as

module members without :impoprted-members: option

* #6889: autodoc: Trailing comma in ``:members::`` option causes cryptic warning

* #6568: autosummary: ``autosummary_imported_members`` is ignored on generating

a stub file for submodule

* #7055: linkcheck: redirect is treated as an error

* #7088: HTML template: If ``navigation_with_keys`` option is activated,

modifier keys are ignored, which means the feature can interfere with browser

features

* #7090: std domain: Can't assign numfig-numbers for custom container nodes

* #7106: std domain: enumerated nodes are marked as duplicated when extensions

call ``note_explicit_target()``

* #7095: dirhtml: Cross references are broken via intersphinx and ``:doc:`` role

* C++:

- Don't crash when using the ``struct`` role in some cases.

- Don't warn when using the ``var``/``member`` role for function

parameters.

- Render call and braced-init expressions correctly.

* #7097: Filenames of images generated by

``sphinx.transforms.post_transforms.images.ImageConverter``

or its subclasses (used for latex build) are now sanitized,

to prevent broken paths

Release 2.3.1 (released Dec 22, 2019)

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

Bugs fixed

----------

* #6936: sphinx-autogen: raises AttributeError

Release 2.3.0 (released Dec 15, 2019)

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

Incompatible changes

--------------------

* #6742: ``end-before`` option of :rst:dir:`literalinclude` directive does not

match the first line of the code block.

* #1331: Change default User-Agent header to ``"Sphinx/X.Y.Z requests/X.Y.Z

python/X.Y.Z"``. It can be changed via :confval:`user_agent`.

* #6867: text: content of admonitions starts after a blank line

Deprecated

----------

* ``sphinx.builders.gettext.POHEADER``

* ``sphinx.io.SphinxStandaloneReader.app``

* ``sphinx.io.SphinxStandaloneReader.env``

* ``sphinx.util.texescape.tex_escape_map``

* ``sphinx.util.texescape.tex_hl_escape_map_new``

* ``sphinx.writers.latex.LaTeXTranslator.no_contractions``

Features added

--------------

* #6707: C++, support bit-fields.

* #267: html: Eliminate prompt characters of doctest block from copyable text

* #6548: html: Use favicon for OpenSearch if available

* #6729: html theme: agogo theme now supports ``rightsidebar`` option

* #6780: Add PEP-561 Support

* #6762: latex: Allow to load additonal LaTeX packages via ``extrapackages`` key

of :confval:`latex_elements`

* #1331: Add new config variable: :confval:`user_agent`

* #6000: LaTeX: have backslash also be an inline literal word wrap break

character

* #4186: LaTeX: Support upLaTeX as a new :confval:`latex_engine` (experimental)

* #6812: Improve a warning message when extensions are not parallel safe

* #6818: Improve Intersphinx performance for multiple remote inventories.

* #2546: apidoc: .so file support

* #6798: autosummary: emit ``autodoc-skip-member`` event on generating stub file

* #6483: i18n: make explicit titles in toctree translatable

* #6816: linkcheck: Add :confval:`linkcheck_auth` option to provide

authentication information when doing ``linkcheck`` builds

* #6872: linkcheck: Handles HTTP 308 Permanent Redirect

* #6613: html: Wrap section number in span tag

* #6781: gettext: Add :confval:`gettext_last_translator' and

:confval:`gettext_language_team` to customize headers of POT file

Bugs fixed

----------

* #6668: LaTeX: Longtable before header has incorrect distance

(refs: `latex3/latex2e#173`_)

.. _latex3/latex2e#173: https://github.com/latex3/latex2e/issues/173

* #6618: LaTeX: Avoid section names at the end of a page

* #6738: LaTeX: Do not replace unicode characters by LaTeX macros on unicode

supported LaTeX engines: ¶, §, €, ∞, ±, →, ‣, –, superscript and subscript

digits go through "as is" (as default OpenType font supports them)

* #6704: linkcheck: Be defensive and handle newly defined HTTP error code

* #6806: linkcheck: Failure on parsing content

* #6655: image URLs containing ``data:`` causes gettext builder crashed

* #6584: i18n: Error when compiling message catalogs on Hindi

* #6718: i18n: KeyError is raised if section title and table title are same

* #6743: i18n: :confval:`rst_prolog` breaks the translation

* #6708: mathbase: Some deprecated functions have removed

* #6709: autodoc: mock object does not work as a class decorator

* #5070: epub: Wrong internal href fragment links

* #6712: Allow not to install sphinx.testing as runtime (mainly for ALT Linux)

* #6741: html: search result was broken with empty :confval:`html_file_suffix`

* #6001: LaTeX does not wrap long code lines at backslash character

* #6804: LaTeX: PDF build breaks if admonition of danger type contains

code-block long enough not to fit on one page

* #6809: LaTeX: code-block in a danger type admonition can easily spill over

bottom of page

* #6793: texinfo: Code examples broken following "sidebar"

* #6813: An orphan warning is emitted for included document on Windows. Thanks

to @drillan

* #6850: Fix smartypants module calls re.sub() with wrong options

* #6824: HTML search: If a search term is partially matched in the title and

fully matched in a text paragraph on the same page, the search does not

include this match.

* #6848: config.py shouldn't pop extensions from overrides

* #6867: text: extra spaces are inserted to hyphenated words on folding lines

* #6886: LaTeX: xelatex converts straight double quotes into right curly ones

(shows when :confval:`smartquotes` is ``False``)

* #6890: LaTeX: even with smartquotes off, PDF output transforms straight

quotes and consecutive hyphens into curly quotes and dashes

* #6876: LaTeX: multi-line display of authors on title page has ragged edges

* #6887: Sphinx crashes with docutils-0.16b0

* #6920: sphinx-build: A console message is wrongly highlighted

* #6900: sphinx-build: ``-D`` option does not considers ``0`` and ``1`` as a

boolean value

Release 2.2.2 (released Dec 03, 2019)

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

Incompatible changes

--------------------

* #6803: For security reason of python, parallel mode is disabled on macOS and

Python3.8+

Bugs fixed

----------

* #6776: LaTeX: 2019-10-01 LaTeX release breaks :file:`sphinxcyrillic.sty`

* #6815: i18n: French, Hindi, Chinese, Japanese and Korean translation messages

has been broken

* #6803: parallel build causes AttributeError on macOS and Python3.8

Release 2.2.1 (released Oct 26, 2019)

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

Bugs fixed

----------

* #6641: LaTeX: Undefined control sequence ``\sphinxmaketitle``

* #6710: LaTeX not well configured for Greek language as main language

* #6759: validation of html static paths and extra paths no longer throws

an error if the paths are in different directories

Release 2.2.0 (released Aug 19, 2019)

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

Incompatible changes

--------------------

* apidoc: template files are renamed to ``.rst_t``

* html: Field lists will be styled by grid layout

Deprecated

----------

* ``sphinx.domains.math.MathDomain.add_equation()``

* ``sphinx.domains.math.MathDomain.get_next_equation_number()``

* The ``info`` and ``warn`` arguments of

``sphinx.ext.autosummary.generate.generate_autosummary_docs()``

* ``sphinx.ext.autosummary.generate._simple_info()``

* ``sphinx.ext.autosummary.generate._simple_warn()``

* ``sphinx.ext.todo.merge_info()``

* ``sphinx.ext.todo.process_todo_nodes()``

* ``sphinx.ext.todo.process_todos()``

* ``sphinx.ext.todo.purge_todos()``

Features added

--------------

* #5124: graphviz: ``:graphviz_dot:`` option is renamed to ``:layout:``

* #1464: html: emit a warning if :confval:`html_static_path` and

:confval:`html_extra_path` directories are inside output directory

* #6514: html: Add a label to search input for accessability purposes

* #5602: apidoc: Add ``--templatedir`` option

* #6475: Add ``override`` argument to ``app.add_autodocumenter()``

* #6310: imgmath: let :confval:`imgmath_use_preview` work also with the SVG

format for images rendering inline math

* #6533: LaTeX: refactor visit_enumerated_list() to use ``\sphinxsetlistlabels``

* #6628: quickstart: Use ``https://docs.python.org/3/`` for default setting of

:confval:`intersphinx_mapping`

* #6419: sphinx-build: give reasons why rebuilded

Bugs fixed

----------

* py domain: duplicated warning does not point the location of source code

* #6499: html: Sphinx never updates a copy of :confval:`html_logo` even if

original file has changed

* #1125: html theme: scrollbar is hard to see on classic theme and macOS

* #5502: linkcheck: Consider HTTP 503 response as not an error

* #6439: Make generated download links reproducible

* #6486: UnboundLocalError is raised if broken extension installed

* #6567: autodoc: :confval:`autodoc_inherit_docstrings` does not effect to

``__init__()`` and ``__new__()``

* #6574: autodoc: :confval:`autodoc_member_order` does not refer order of

imports when ``'bysource'`` order

* #6574: autodoc: missing type annotation for variadic and keyword parameters

* #6589: autodoc: Formatting issues with autodoc_typehints='none'

* #6605: autodoc: crashed when target code contains custom method-like objects

* #6498: autosummary: crashed with wrong autosummary_generate setting

* #6507: autosummary: crashes without no autosummary_generate setting

* #6511: LaTeX: autonumbered list can not be customized in LaTeX

since Sphinx 1.8.0 (refs: #6533)

* #6531: Failed to load last environment object when extension added

* #736: Invalid sort in pair index

* #6527: :confval:`last_updated` wrongly assumes timezone as UTC

* #5592: std domain: :rst:dir:`option` directive registers an index entry for

each comma separated option

* #6549: sphinx-build: Escaped characters in error messages

* #6545: doctest comments not getting trimmed since Sphinx 1.8.0

* #6561: glossary: Wrong hyperlinks are generated for non alphanumeric terms

* #6620: i18n: classifiers of definition list are not translated with

docutils-0.15

* #6474: ``DocFieldTransformer`` raises AttributeError when given directive is

not a subclass of ObjectDescription

Release 2.1.2 (released Jun 19, 2019)

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

Bugs fixed

----------

* #6497: custom lexers fails highlighting when syntax error

* #6478, #6488: info field lists are incorrectly recognized

Release 2.1.1 (released Jun 10, 2019)

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

Incompatible changes

--------------------

* #6447: autodoc: Stop to generate document for undocumented module variables

Bugs fixed

----------

* #6442: LaTeX: admonitions of :rst:dir:`note` type can get separated from

immediately preceding section title by pagebreak

* #6448: autodoc: crashed when autodocumenting classes with ``__slots__ = None``

* #6451: autodoc: generates docs for "optional import"ed modules as variables

* #6452: autosummary: crashed when generating document of properties

* #6455: napoleon: docstrings for properties are not processed

* #6436: napoleon: "Unknown target name" error if variable name ends with

underscore

* #6440: apidoc: missing blank lines between modules

Release 2.1.0 (released Jun 02, 2019)

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

Incompatible changes

--------------------

* Ignore filenames without file extension given to ``Builder.build_specific()``

API directly

* #6230: The anchor of term in glossary directive is changed if it is consisted

by non-ASCII characters

* #4550: html: Centering tables by default using CSS

* #6239: latex: xelatex and xeCJK are used for Chinese documents by default

* ``Sphinx.add_lexer()`` now takes a Lexer class instead of instance. An

instance of lexers are still supported until Sphinx-3.x.

Deprecated

----------

* ``sphinx.builders.latex.LaTeXBuilder.apply_transforms()``

* ``sphinx.builders._epub_base.EpubBuilder.esc()``

* ``sphinx.directives.Acks``

* ``sphinx.directives.Author``

* ``sphinx.directives.Centered``

* ``sphinx.directives.Class``

* ``sphinx.directives.CodeBlock``

* ``sphinx.directives.Figure``

* ``sphinx.directives.HList``

* ``sphinx.directives.Highlight``

* ``sphinx.directives.Include``

* ``sphinx.directives.Index``

* ``sphinx.directives.LiteralInclude``

* ``sphinx.directives.Meta``

* ``sphinx.directives.Only``

* ``sphinx.directives.SeeAlso``

* ``sphinx.directives.TabularColumns``

* ``sphinx.directives.TocTree``

* ``sphinx.directives.VersionChange``

* ``sphinx.domains.python.PyClassmember``

* ``sphinx.domains.python.PyModulelevel``

* ``sphinx.domains.std.StandardDomain._resolve_citation_xref()``

* ``sphinx.domains.std.StandardDomain.note_citations()``

* ``sphinx.domains.std.StandardDomain.note_citation_refs()``

* ``sphinx.domains.std.StandardDomain.note_labels()``

* ``sphinx.environment.NoUri``

* ``sphinx.ext.apidoc.format_directive()``

* ``sphinx.ext.apidoc.format_heading()``

* ``sphinx.ext.apidoc.makename()``

* ``sphinx.ext.autodoc.importer.MockFinder``

* ``sphinx.ext.autodoc.importer.MockLoader``

* ``sphinx.ext.autodoc.importer.mock()``

* ``sphinx.ext.autosummary.autolink_role()``

* ``sphinx.ext.imgmath.DOC_BODY``

* ``sphinx.ext.imgmath.DOC_BODY_PREVIEW``

* ``sphinx.ext.imgmath.DOC_HEAD``

* ``sphinx.transforms.CitationReferences``

* ``sphinx.transforms.SmartQuotesSkipper``

* ``sphinx.util.docfields.DocFieldTransformer.preprocess_fieldtypes()``

* ``sphinx.util.node.find_source_node()``

* ``sphinx.util.i18n.find_catalog()``

* ``sphinx.util.i18n.find_catalog_files()``

* ``sphinx.util.i18n.find_catalog_source_files()``

For more details, see :ref:`deprecation APIs list <dev-deprecated-apis>`.

Features added

--------------

* Add a helper class ``sphinx.transforms.post_transforms.SphinxPostTransform``

* Add helper methods

- ``PythonDomain.note_module()``

- ``PythonDomain.note_object()``

- ``SphinxDirective.set_source_info()``

* #6180: Support ``--keep-going`` with BuildDoc setup command

* ``math`` directive now supports ``:class:`` option

* todo: ``todo`` directive now supports ``:name:`` option

* Enable override via environment of ``SPHINXOPTS`` and ``SPHINXBUILD`` Makefile

variables (refs: #6232, #6303)

* #6287: autodoc: Unable to document bound instance methods exported as module

functions

* #6289: autodoc: :confval:`autodoc_default_options` now supports

``imported-members`` option

* #4777: autodoc: Support coroutine

* #744: autodoc: Support abstractmethod

* #6325: autodoc: Support attributes in __slots__. For dict-style __slots__,

autodoc considers values as a docstring of the attribute

* #6361: autodoc: Add :confval:`autodoc_typehints` to suppress typehints from

signature

* #1063: autodoc: ``automodule`` directive now handles undocumented module level

variables

* #6212 autosummary: Add :confval:`autosummary_imported_members` to display

imported members on autosummary

* #6271: ``make clean`` is catastrophically broken if building into '.'

* #6363: Support ``%O%`` environment variable in make.bat

* #4777: py domain: Add ``:async:`` option to :rst:dir:`py:function` directive

* py domain: Add new options to :rst:dir:`py:method` directive

- ``:abstractmethod:``

- ``:async:``

- ``:classmethod:``

- ``:property:``

- ``:staticmethod:``

* rst domain: Add :rst:dir:`directive:option` directive to describe the option

for directive

* #6306: html: Add a label to search form for accessability purposes

* #4390: html: Consistent and semantic CSS for signatures

* #6358: The ``rawsource`` property of ``production`` nodes now contains the

full production rule

* #6373: autosectionlabel: Allow suppression of warnings

* coverage: Support a new ``coverage_ignore_pyobjects`` option

* #6239: latex: Support to build Chinese documents

Bugs fixed

----------

* #6230: Inappropriate node_id has been generated by glossary directive if term

is consisted by non-ASCII characters

* #6213: ifconfig: contents after headings are not shown

* commented term in glossary directive is wrongly recognized

* #6299: rst domain: rst:directive directive generates waste space

* #6379: py domain: Module index (py-modindex.html) has duplicate titles

* #6331: man: invalid output when doctest follows rubric

* #6351: "Hyperlink target is not referenced" message is shown even if

referenced

* #6165: autodoc: ``tab_width`` setting of docutils has been ignored

* #6347: autodoc: crashes with a plain Tuple on Python 3.6 and 3.5

* #6311: autosummary: autosummary table gets confused by complex type hints

* #6350: autosummary: confused by an argument having some kind of default value

* Generated Makefiles lack a final EOL (refs: #6232)

* #6375: extlinks: Cannot escape angle brackets in link caption

* #6378: linkcheck: Send commonly used User-Agent

* #6387: html search: failed to search document with haiku and scrolls themes

* #6408: html search: Fix the ranking of search results

* #6406: Wrong year is returned for ``SOURCE_DATE_EPOCH``

* #6402: image directive crashes by unknown image format

* #6286: C++, allow 8 and 9 in hexadecimal integer literals.

* #6305: Fix the string in quickstart for 'path' argument of parser

* LaTeX: Figures in admonitions produced errors (refs: #6364)

Release 2.0.1 (released Apr 08, 2019)

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

Bugs fixed

----------

* LaTeX: some system labels are not translated

* RemovedInSphinx30Warning is marked as pending

* deprecation warnings are not emitted

- sphinx.application.CONFIG_FILENAME

- sphinx.builders.htmlhelp

- :confval:`viewcode_import`

* #6208: C++, properly parse full xrefs that happen to have a short xref as

prefix

* #6220, #6225: napoleon: AttributeError is raised for raised section having

references

* #6245: circular import error on importing SerializingHTMLBuilder

* #6243: LaTeX: 'releasename' setting for latex_elements is ignored

* #6244: html: Search function is broken with 3rd party themes

* #6263: html: HTML5Translator crashed with invalid field node

* #6262: html theme: The style of field lists has changed in bizstyle theme

Release 2.0.0 (released Mar 29, 2019)

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

Dependencies

------------

2.0.0b1

* LaTeX builder now depends on TeX Live 2015 or above.

* LaTeX builder (with ``'pdflatex'`` :confval:`latex_engine`) will process

Unicode Greek letters in text (not in math mark-up) via the text font and

will not escape them to math mark-up. See the discussion of the

``'fontenc'`` key of :confval:`latex_elements`; such (optional) support for

Greek adds, for example on Ubuntu xenial, the ``texlive-lang-greek`` and (if

default font set-up is not modified) ``cm-super(-minimal)`` as additional

Sphinx LaTeX requirements.

* LaTeX builder with :confval:`latex_engine` set to ``'xelatex'`` or to

``'lualatex'`` requires (by default) the ``FreeFont`` fonts,

which in Ubuntu xenial are provided by package ``fonts-freefont-otf``, and

e.g. in Fedora 29 via package ``texlive-gnu-freefont``.

* requests 2.5.0 or above

* The six package is no longer a dependency

* The sphinxcontrib-websupport package is no longer a dependency

* Some packages are separated to sub packages:

- sphinxcontrib.applehelp

- sphinxcontrib.devhelp

- sphinxcontrib.htmlhelp

- sphinxcontrib.jsmath

- sphinxcontrib.serializinghtml

- sphinxcontrib.qthelp

Incompatible changes

--------------------

2.0.0b1

* Drop python 2.7 and 3.4 support

* Drop docutils 0.11 support

* Drop features and APIs deprecated in 1.7.x

* The default setting for :confval:`master_doc` is changed to ``'index'`` which

has been longly used as default of sphinx-quickstart.

* LaTeX: Move message resources to ``sphinxmessage.sty``

* LaTeX: Stop using ``\captions<lang>`` macro for some labels

* LaTeX: for ``'xelatex'`` and ``'lualatex'``, use the ``FreeFont`` OpenType

fonts as default choice (refs: #5645)

* LaTeX: ``'xelatex'`` and ``'lualatex'`` now use ``\small`` in code-blocks

(due to ``FreeMono`` character width) like ``'pdflatex'`` already did (due

to ``Courier`` character width). You may need to adjust this via

:confval:`latex_elements` ``'fvset'`` key, in case of usage of some other

OpenType fonts (refs: #5768)

* LaTeX: Greek letters in text are not escaped to math mode mark-up, and they

will use the text font not the math font. The ``LGR`` font encoding must be

added to the ``'fontenc'`` key of :confval:`latex_elements` for this to work

(only if it is needed by the document, of course).

* LaTeX: setting the :confval:`language` to ``'en'`` triggered ``Sonny`` option

of ``fncychap``, now it is ``Bjarne`` to match case of no language specified.

(refs: #5772)

* #5770: doctest: Follow :confval:`highlight_language` on highlighting doctest

block. As a result, they are highlighted as python3 by default.

* The order of argument for ``HTMLTranslator``, ``HTML5Translator`` and

``ManualPageTranslator`` are changed

* LaTeX: hard-coded redefinitions of ``\l@section`` and ``\l@subsection``

formerly done during loading of ``'manual'`` docclass get executed later, at

time of ``\sphinxtableofcontents``. This means that custom user definitions

from LaTeX preamble now get overwritten. Use ``\sphinxtableofcontentshook``

to insert custom user definitions. See :ref:`latex-macros`.

* quickstart: Simplify generated ``conf.py``

* #4148: quickstart: some questions are removed. They are still able to specify

via command line options

* websupport: unbundled from sphinx core. Please use sphinxcontrib-websupport

* C++, the visibility of base classes is now always rendered as present in the

input. That is, ``private`` is now shown, where it was ellided before.

* LaTeX: graphics inclusion of oversized images rescales to not exceed

the text width and height, even if width and/or height option were used.

(refs: #5956)

* epub: ``epub_title`` defaults to the :confval:`project` option

* #4550: All tables and figures without ``align`` option are displayed to center

* #4587: html: Output HTML5 by default

2.0.0b2

* texinfo: image files are copied into ``name-figure`` directory

Deprecated

----------

2.0.0b1

* Support for evaluating Python 2 syntax is deprecated. This includes

configuration files which should be converted to Python 3.

* The arguments of ``EpubBuilder.build_mimetype()``,

``EpubBuilder.build_container()``, ``EpubBuilder.bulid_content()``,

``EpubBuilder.build_toc()`` and ``EpubBuilder.build_epub()``

* The arguments of ``Epub3Builder.build_navigation_doc()``

* The config variables

- :confval:`html_experimental_html5_writer`

* The ``encoding`` argument of ``autodoc.Documenter.get_doc()``,

``autodoc.DocstringSignatureMixin.get_doc()``,

``autodoc.DocstringSignatureMixin._find_signature()``, and

``autodoc.ClassDocumenter.get_doc()`` are deprecated.

* The ``importer`` argument of ``sphinx.ext.autodoc.importer._MockModule``

* The ``nodetype`` argument of ``sphinx.search.WordCollector.

is_meta_keywords()``

* The ``suffix`` argument of ``env.doc2path()`` is deprecated.

* The string style ``base`` argument of ``env.doc2path()`` is deprecated.

* The fallback to allow omitting the ``filename`` argument from an overridden

``IndexBuilder.feed()`` method is deprecated.

* ``sphinx.addnodes.abbreviation``

* ``sphinx.application.Sphinx._setting_up_extension``

* ``sphinx.builders.epub3.Epub3Builder.validate_config_value()``

* ``sphinx.builders.html.SingleFileHTMLBuilder``

* ``sphinx.builders.htmlhelp.HTMLHelpBuilder.open_file()``

* ``sphinx.cmd.quickstart.term_decode()``

* ``sphinx.cmd.quickstart.TERM_ENCODING``

* ``sphinx.config.check_unicode()``

* ``sphinx.config.string_classes``

* ``sphinx.domains.cpp.DefinitionError.description``

* ``sphinx.domains.cpp.NoOldIdError.description``

* ``sphinx.domains.cpp.UnsupportedMultiCharacterCharLiteral.decoded``

* ``sphinx.ext.autodoc.importer._MockImporter``

* ``sphinx.ext.autosummary.Autosummary.warn()``

* ``sphinx.ext.autosummary.Autosummary.genopt``

* ``sphinx.ext.autosummary.Autosummary.warnings``

* ``sphinx.ext.autosummary.Autosummary.result``

* ``sphinx.ext.doctest.doctest_encode()``

* ``sphinx.io.SphinxBaseFileInput``

* ``sphinx.io.SphinxFileInput.supported``

* ``sphinx.io.SphinxRSTFileInput``

* ``sphinx.registry.SphinxComponentRegistry.add_source_input()``

* ``sphinx.roles.abbr_role()``

* ``sphinx.roles.emph_literal_role()``

* ``sphinx.roles.menusel_role()``

* ``sphinx.roles.index_role()``

* ``sphinx.roles.indexmarkup_role()``

* ``sphinx.testing.util.remove_unicode_literal()``

* ``sphinx.util.attrdict``

* ``sphinx.util.force_decode()``

* ``sphinx.util.get_matching_docs()``

* ``sphinx.util.inspect.Parameter``

* ``sphinx.util.jsonimpl``

* ``sphinx.util.osutil.EEXIST``

* ``sphinx.util.osutil.EINVAL``

* ``sphinx.util.osutil.ENOENT``

* ``sphinx.util.osutil.EPIPE``

* ``sphinx.util.osutil.walk()``

* ``sphinx.util.PeekableIterator``

* ``sphinx.util.pycompat.NoneType``

* ``sphinx.util.pycompat.TextIOWrapper``

* ``sphinx.util.pycompat.UnicodeMixin``

* ``sphinx.util.pycompat.htmlescape``

* ``sphinx.util.pycompat.indent``

* ``sphinx.util.pycompat.sys_encoding``

* ``sphinx.util.pycompat.terminal_safe()``

* ``sphinx.util.pycompat.u``

* ``sphinx.writers.latex.ExtBabel``

* ``sphinx.writers.latex.LaTeXTranslator._make_visit_admonition()``

* ``sphinx.writers.latex.LaTeXTranslator.babel_defmacro()``

* ``sphinx.writers.latex.LaTeXTranslator.collect_footnotes()``

* ``sphinx.writers.latex.LaTeXTranslator.generate_numfig_format()``

* ``sphinx.writers.texinfo.TexinfoTranslator._make_visit_admonition()``

* ``sphinx.writers.text.TextTranslator._make_depart_admonition()``

* template variables for LaTeX template

- ``logo``

- ``numfig_format``

- ``pageautorefname``

- ``translatablestrings``

For more details, see :ref:`deprecation APIs list <dev-deprecated-apis>`.