Adding upstream version 5.3.0.upstream/5.3.0upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

14 files changed, 3100 insertions, 0 deletions

diff --git a/doc/extdev/appapi.rst b/doc/extdev/appapi.rst
new file mode 100644
index 0000000..fc92a77
--- /dev/null
+++ b/doc/extdev/appapi.rst
@@ -0,0 +1,456 @@
+.. highlight:: rest
+
+Application API
+===============
+
+.. module:: sphinx.application
+   :synopsis: Application class and extensibility interface.
+
+
+Each Sphinx extension is a Python module with at least a :func:`setup`
+function.  This function is called at initialization time with one argument,
+the application object representing the Sphinx process.
+
+.. class:: Sphinx
+
+   This application object has the public API described in the following.
+
+Extension setup
+---------------
+
+These methods are usually called in an extension's ``setup()`` function.
+
+Examples of using the Sphinx extension API can be seen in the :mod:`sphinx.ext`
+package.
+
+.. currentmodule:: sphinx.application
+
+.. automethod:: Sphinx.setup_extension
+
+.. automethod:: Sphinx.require_sphinx
+
+.. automethod:: Sphinx.connect
+
+.. automethod:: Sphinx.disconnect
+
+.. automethod:: Sphinx.add_builder
+
+.. automethod:: Sphinx.add_config_value
+
+.. automethod:: Sphinx.add_event
+
+.. automethod:: Sphinx.set_translator
+
+.. automethod:: Sphinx.add_node
+
+.. automethod:: Sphinx.add_enumerable_node
+
+.. automethod:: Sphinx.add_directive
+
+.. automethod:: Sphinx.add_role
+
+.. automethod:: Sphinx.add_generic_role
+
+.. automethod:: Sphinx.add_domain
+
+.. automethod:: Sphinx.add_directive_to_domain
+
+.. automethod:: Sphinx.add_role_to_domain
+
+.. automethod:: Sphinx.add_index_to_domain
+
+.. automethod:: Sphinx.add_object_type
+
+.. automethod:: Sphinx.add_crossref_type
+
+.. automethod:: Sphinx.add_transform
+
+.. automethod:: Sphinx.add_post_transform
+
+.. automethod:: Sphinx.add_js_file
+
+.. automethod:: Sphinx.add_css_file
+
+.. automethod:: Sphinx.add_latex_package
+
+.. automethod:: Sphinx.add_lexer
+
+.. automethod:: Sphinx.add_autodocumenter
+
+.. automethod:: Sphinx.add_autodoc_attrgetter
+
+.. automethod:: Sphinx.add_search_language
+
+.. automethod:: Sphinx.add_source_suffix
+
+.. automethod:: Sphinx.add_source_parser
+
+.. automethod:: Sphinx.add_env_collector
+
+.. automethod:: Sphinx.add_html_theme
+
+.. automethod:: Sphinx.add_html_math_renderer
+
+.. automethod:: Sphinx.add_message_catalog
+
+.. automethod:: Sphinx.is_parallel_allowed
+
+.. exception:: ExtensionError
+
+   All these methods raise this exception if something went wrong with the
+   extension API.
+
+
+Emitting events
+---------------
+
+.. class:: Sphinx
+   :noindex:
+
+   .. automethod:: emit
+
+   .. automethod:: emit_firstresult
+
+
+Sphinx runtime information
+--------------------------
+
+The application object also provides runtime information as attributes.
+
+.. attribute:: Sphinx.project
+
+   Target project.  See :class:`.Project`.
+
+.. attribute:: Sphinx.srcdir
+
+   Source directory.
+
+.. attribute:: Sphinx.confdir
+
+   Directory containing ``conf.py``.
+
+.. attribute:: Sphinx.doctreedir
+
+   Directory for storing pickled doctrees.
+
+.. attribute:: Sphinx.outdir
+
+   Directory for storing built document.
+
+
+.. _events:
+
+Sphinx core events
+------------------
+
+These events are known to the core.  The arguments shown are given to the
+registered event handlers.  Use :meth:`.Sphinx.connect` in an extension's
+``setup`` function (note that ``conf.py`` can also have a ``setup`` function) to
+connect handlers to the events.  Example:
+
+.. code-block:: python
+
+   def source_read_handler(app, docname, source):
+       print('do something here...')
+
+   def setup(app):
+       app.connect('source-read', source_read_handler)
+
+
+Below is an overview of each event that happens during a build. In the list
+below, we include the event name, its callback parameters, and the input and output
+type for that event:
+
+.. code-block:: none
+
+   1. event.config-inited(app,config)
+   2. event.builder-inited(app)
+   3. event.env-get-outdated(app, env, added, changed, removed)
+   4. event.env-before-read-docs(app, env, docnames)
+
+   for docname in docnames:
+      5. event.env-purge-doc(app, env, docname)
+
+      if doc changed and not removed:
+         6. source-read(app, docname, source)
+         7. run source parsers: text -> docutils.document
+            - parsers can be added with the app.add_source_parser() API
+         8. apply transforms based on priority: docutils.document -> docutils.document
+            - event.doctree-read(app, doctree) is called in the middle of transforms,
+              transforms come before/after this event depending on their priority.
+
+   9. event.env-merge-info(app, env, docnames, other)
+      - if running in parallel mode, this event will be emitted for each process
+
+   10. event.env-updated(app, env)
+   11. event.env-get-updated(app, env)
+   12. event.env-check-consistency(app, env)
+
+   # The updated-docs list can be builder dependent, but generally includes all new/changed documents,
+   # plus any output from `env-get-updated`, and then all "parent" documents in the ToC tree
+   # For builders that output a single page, they are first joined into a single doctree before post-transforms
+   # or the doctree-resolved event is emitted
+   for docname in updated-docs:
+      13. apply post-transforms (by priority): docutils.document -> docutils.document
+      14. event.doctree-resolved(app, doctree, docname)
+          - In the event that any reference nodes fail to resolve, the following may emit:
+          - event.missing-reference(env, node, contnode)
+          - event.warn-missing-reference(domain, node)
+
+   15. Generate output files
+   16. event.build-finished(app, exception)
+
+Here is a more detailed list of these events.
+
+.. event:: builder-inited (app)
+
+   Emitted when the builder object has been created.  It is available as
+   ``app.builder``.
+
+.. event:: config-inited (app, config)
+
+   Emitted when the config object has been initialized.
+
+   .. versionadded:: 1.8
+
+.. event:: env-get-outdated (app, env, added, changed, removed)
+
+   Emitted when the environment determines which source files have changed and
+   should be re-read.  *added*, *changed* and *removed* are sets of docnames
+   that the environment has determined.  You can return a list of docnames to
+   re-read in addition to these.
+
+   .. versionadded:: 1.1
+
+.. event:: env-purge-doc (app, env, docname)
+
+   Emitted when all traces of a source file should be cleaned from the
+   environment, that is, if the source file is removed or before it is freshly
+   read.  This is for extensions that keep their own caches in attributes of the
+   environment.
+
+   For example, there is a cache of all modules on the environment.  When a
+   source file has been changed, the cache's entries for the file are cleared,
+   since the module declarations could have been removed from the file.
+
+   .. versionadded:: 0.5
+
+.. event:: env-before-read-docs (app, env, docnames)
+
+   Emitted after the environment has determined the list of all added and
+   changed files and just before it reads them.  It allows extension authors to
+   reorder the list of docnames (*inplace*) before processing, or add more
+   docnames that Sphinx did not consider changed (but never add any docnames
+   that are not in ``env.found_docs``).
+
+   You can also remove document names; do this with caution since it will make
+   Sphinx treat changed files as unchanged.
+
+   .. versionadded:: 1.3
+
+.. event:: source-read (app, docname, source)
+
+   Emitted when a source file has been read.  The *source* argument is a list
+   whose single element is the contents of the source file.  You can process the
+   contents and replace this item to implement source-level transformations.
+
+   For example, if you want to use ``$`` signs to delimit inline math, like in
+   LaTeX, you can use a regular expression to replace ``$...$`` by
+   ``:math:`...```.
+
+   .. versionadded:: 0.5
+
+.. event:: object-description-transform (app, domain, objtype, contentnode)
+
+   Emitted when an object description directive has run.  The *domain* and
+   *objtype* arguments are strings indicating object description of the object.
+   And *contentnode* is a content for the object.  It can be modified in-place.
+
+   .. versionadded:: 2.4
+
+.. event:: doctree-read (app, doctree)
+
+   Emitted when a doctree has been parsed and read by the environment, and is
+   about to be pickled.  The *doctree* can be modified in-place.
+
+.. event:: missing-reference (app, env, node, contnode)
+
+   Emitted when a cross-reference to an object cannot be resolved.
+   If the event handler can resolve the reference, it should return a
+   new docutils node to be inserted in the document tree in place of the node
+   *node*.  Usually this node is a :class:`reference` node containing *contnode*
+   as a child.
+   If the handler can not resolve the cross-reference,
+   it can either return ``None`` to let other handlers try,
+   or raise :class:`NoUri` to prevent other handlers in trying and suppress
+   a warning about this cross-reference being unresolved.
+
+   :param env: The build environment (``app.builder.env``).
+   :param node: The :class:`pending_xref` node to be resolved.  Its attributes
+      ``reftype``, ``reftarget``, ``modname`` and ``classname`` attributes
+      determine the type and target of the reference.
+   :param contnode: The node that carries the text and formatting inside the
+      future reference and should be a child of the returned reference node.
+
+   .. versionadded:: 0.5
+
+.. event:: warn-missing-reference (app, domain, node)
+
+   Emitted when a cross-reference to an object cannot be resolved even after
+   :event:`missing-reference`.  If the event handler can emit warnings for
+   the missing reference, it should return ``True``. The configuration variables
+   :confval:`nitpick_ignore` and :confval:`nitpick_ignore_regex` prevent the
+   event from being emitted for the corresponding nodes.
+
+   .. versionadded:: 3.4
+
+.. event:: doctree-resolved (app, doctree, docname)
+
+   Emitted when a doctree has been "resolved" by the environment, that is, all
+   references have been resolved and TOCs have been inserted.  The *doctree* can
+   be modified in place.
+
+   Here is the place to replace custom nodes that don't have visitor methods in
+   the writers, so that they don't cause errors when the writers encounter them.
+
+.. event:: env-merge-info (app, env, docnames, other)
+
+   This event is only emitted when parallel reading of documents is enabled.  It
+   is emitted once for every subprocess that has read some documents.
+
+   You must handle this event in an extension that stores data in the
+   environment in a custom location.  Otherwise the environment in the main
+   process will not be aware of the information stored in the subprocess.
+
+   *other* is the environment object from the subprocess, *env* is the
+   environment from the main process.  *docnames* is a set of document names
+   that have been read in the subprocess.
+
+   .. versionadded:: 1.3
+
+.. event:: env-updated (app, env)
+
+   Emitted when the :meth:`update` method of the build environment has
+   completed, that is, the environment and all doctrees are now up-to-date.
+
+   You can return an iterable of docnames from the handler.  These documents
+   will then be considered updated, and will be (re-)written during the writing
+   phase.
+
+   .. versionadded:: 0.5
+
+   .. versionchanged:: 1.3
+      The handlers' return value is now used.
+
+.. event:: env-check-consistency (app, env)
+
+   Emitted when Consistency checks phase.  You can check consistency of
+   metadata for whole of documents.
+
+   .. versionadded:: 1.6
+
+      As a **experimental** event
+
+.. event:: html-collect-pages (app)
+
+   Emitted when the HTML builder is starting to write non-document pages.  You
+   can add pages to write by returning an iterable from this event consisting of
+   ``(pagename, context, templatename)``.
+
+   .. versionadded:: 1.0
+
+.. event:: html-page-context (app, pagename, templatename, context, doctree)
+
+   Emitted when the HTML builder has created a context dictionary to render a
+   template with -- this can be used to add custom elements to the context.
+
+   The *pagename* argument is the canonical name of the page being rendered,
+   that is, without ``.html`` suffix and using slashes as path separators.  The
+   *templatename* is the name of the template to render, this will be
+   ``'page.html'`` for all pages from reST documents.
+
+   The *context* argument is a dictionary of values that are given to the
+   template engine to render the page and can be modified to include custom
+   values.  Keys must be strings.
+
+   The *doctree* argument will be a doctree when the page is created from a reST
+   documents; it will be ``None`` when the page is created from an HTML template
+   alone.
+
+   You can return a string from the handler, it will then replace
+   ``'page.html'`` as the HTML template for this page.
+
+   .. note:: You can install JS/CSS files for the specific page via
+             :meth:`Sphinx.add_js_file` and :meth:`Sphinx.add_css_file` since
+             v3.5.0.
+
+   .. versionadded:: 0.4
+
+   .. versionchanged:: 1.3
+      The return value can now specify a template name.
+
+.. event:: linkcheck-process-uri (app, uri)
+
+   Emitted when the linkcheck builder collects hyperlinks from document.  *uri*
+   is a collected URI.  The event handlers can modify the URI by returning a
+   string.
+
+   .. versionadded:: 4.1
+
+.. event:: build-finished (app, exception)
+
+   Emitted when a build has finished, before Sphinx exits, usually used for
+   cleanup.  This event is emitted even when the build process raised an
+   exception, given as the *exception* argument.  The exception is reraised in
+   the application after the event handlers have run.  If the build process
+   raised no exception, *exception* will be ``None``.  This allows to customize
+   cleanup actions depending on the exception status.
+
+   .. versionadded:: 0.5
+
+
+Checking the Sphinx version
+---------------------------
+
+.. currentmodule:: sphinx
+
+Use this to adapt your extension to API changes in Sphinx.
+
+.. autodata:: version_info
+
+
+The Config object
+-----------------
+
+.. currentmodule:: sphinx.config
+
+.. autoclass:: Config
+
+
+.. _template-bridge:
+
+The template bridge
+-------------------
+
+.. currentmodule:: sphinx.application
+
+.. autoclass:: TemplateBridge
+   :members:
+
+
+.. _exceptions:
+
+Exceptions
+----------
+
+.. module:: sphinx.errors
+
+.. autoexception:: SphinxError
+
+.. autoexception:: ConfigError
+
+.. autoexception:: ExtensionError
+
+.. autoexception:: ThemeError
+
+.. autoexception:: VersionRequirementError
diff --git a/doc/extdev/builderapi.rst b/doc/extdev/builderapi.rst
new file mode 100644
index 0000000..5c5a525
--- /dev/null
+++ b/doc/extdev/builderapi.rst
@@ -0,0 +1,46 @@
+.. _writing-builders:
+
+Builder API
+===========
+
+.. todo:: Expand this.
+
+.. currentmodule:: sphinx.builders
+
+.. class:: Builder
+
+   This is the base class for all builders.
+
+   These attributes should be set on builder classes:
+
+   .. autoattribute:: name
+   .. autoattribute:: format
+   .. autoattribute:: epilog
+   .. autoattribute:: allow_parallel
+   .. autoattribute:: supported_image_types
+   .. autoattribute:: supported_remote_images
+   .. autoattribute:: supported_data_uri_images
+   .. autoattribute:: default_translator_class
+
+   These methods are predefined and will be called from the application:
+
+   .. automethod:: get_relative_uri
+   .. automethod:: build_all
+   .. automethod:: build_specific
+   .. automethod:: build_update
+   .. automethod:: build
+
+   These methods can be overridden in concrete builder classes:
+
+   .. automethod:: init
+   .. automethod:: get_outdated_docs
+   .. automethod:: get_target_uri
+   .. automethod:: prepare_writing
+   .. automethod:: write_doc
+   .. automethod:: finish
+
+   **Attributes**
+
+   .. attribute:: events
+
+      An :class:`.EventManager` object.
diff --git a/doc/extdev/collectorapi.rst b/doc/extdev/collectorapi.rst
new file mode 100644
index 0000000..cb4c30b
--- /dev/null
+++ b/doc/extdev/collectorapi.rst
@@ -0,0 +1,9 @@
+.. _collector-api:
+
+Environment Collector API
+-------------------------
+
+.. module:: sphinx.environment.collectors
+
+.. autoclass:: EnvironmentCollector
+   :members:
diff --git a/doc/extdev/deprecated.rst b/doc/extdev/deprecated.rst
new file mode 100644
index 0000000..1692f2d
--- /dev/null
+++ b/doc/extdev/deprecated.rst
@@ -0,0 +1,1811 @@
+.. _dev-deprecated-apis:
+
+Deprecated APIs
+===============
+
+On developing Sphinx, we are always careful to the compatibility of our APIs.
+But, sometimes, the change of interface are needed for some reasons.  In such
+cases, we've marked them as deprecated. And they are kept during the two
+major versions (for more details, please see :ref:`deprecation-policy`).
+
+The following is a list of deprecated interfaces.
+
+.. tabularcolumns:: >{\raggedright}\Y{.4}>{\centering}\Y{.1}>{\sphinxcolorblend{!95!red}\centering\noindent\bfseries\color{red}}\Y{.12}>{\raggedright\arraybackslash}\Y{.38}
+
+.. list-table:: deprecated APIs
+   :header-rows: 1
+   :class: deprecated
+   :widths: 40, 10, 10, 40
+
+   * - Target
+     - Deprecated
+     - Removed
+     - Alternatives
+
+   * - HTML 4 support
+     - 5.2
+     - 7.0
+     - N/A
+
+   * - ``sphinx.util.path_stabilize``
+     - 5.1
+     - 7.0
+     - ``sphinx.util.osutil.path_stabilize``
+
+   * - ``sphinx.util.get_matching_files``
+     - 5.1
+     - 7.0
+     - ``sphinx.util.matching.get_matching_files``
+
+   * - ``sphinx.ext.napoleon.iterators``
+     - 5.1
+     - 7.0
+     - ``pockets.iterators``
+
+   * - ``sphinx.util.stemmer``
+     - 5.1
+     - 7.0
+     - ``snowballstemmer``
+
+   * - ``sphinx.util.jsdump``
+     - 5.0
+     - 7.0
+     - The standard library ``json`` module.
+
+   * - :doc:`Setuptools integration </usage/advanced/setuptools>`
+     - 5.0
+     - 7.0
+     - N/A
+
+   * - The ``locale`` argument of ``sphinx.util.i18n:babel_format_date()``
+     - 5.0
+     - 7.0
+     - N/A
+
+   * - The ``language`` argument of ``sphinx.util.i18n:format_date()``
+     - 5.0
+     - 7.0
+     - N/A
+
+   * - ``sphinx.builders.html.html5_ready``
+     - 5.0
+     - 7.0
+     - N/A
+
+   * - ``sphinx.io.read_doc()``
+     - 5.0
+     - 7.0
+     - ``sphinx.builders.Builder.read_doc()``
+
+   * - ``sphinx.util.docutils.__version_info__``
+     - 5.0
+     - 7.0
+     - ``docutils.__version_info__``
+
+   * - ``sphinx.util.docutils.is_html5_writer_available()``
+     - 5.0
+     - 7.0
+     - N/A
+
+   * - ``sphinx.writers.latex.LaTeXWriter.docclasses``
+     - 5.0
+     - 7.0
+     - N/A
+
+   * - ``sphinx.ext.napoleon.docstring.GoogleDocstring._qualify_name()``
+     - 4.5
+     - 6.0
+     - N/A
+
+   * - ``sphinx.ext.autodoc.AttributeDocumenter._datadescriptor``
+     - 4.3
+     - 6.0
+     - N/A
+
+   * - ``sphinx.writers.html.HTMLTranslator._fieldlist_row_index``
+     - 4.3
+     - 6.0
+     - ``sphinx.writers.html.HTMLTranslator._fieldlist_row_indices``
+
+   * - ``sphinx.writers.html.HTMLTranslator._table_row_index``
+     - 4.3
+     - 6.0
+     - ``sphinx.writers.html.HTMLTranslator._table_row_indices``
+
+   * - ``sphinx.writers.html5.HTML5Translator._fieldlist_row_index``
+     - 4.3
+     - 6.0
+     - ``sphinx.writers.html5.HTML5Translator._fieldlist_row_indices``
+
+   * - ``sphinx.writers.html5.HTML5Translator._table_row_index``
+     - 4.3
+     - 6.0
+     - ``sphinx.writers.html5.HTML5Translator._table_row_indices``
+
+   * - The optional argument ``app`` for ``sphinx.environment.BuildEnvironment``
+     - 4.1
+     - 6.0
+     - The required argument
+
+   * - ``sphinx.application.Sphinx.html_theme``
+     - 4.1
+     - 6.0
+     - ``sphinx.registry.SphinxComponentRegistry.html_themes``
+
+   * - ``sphinx.ext.autosummary._app``
+     - 4.1
+     - 6.0
+     - N/A
+
+   * - ``sphinx.util.docstrings.extract_metadata()``
+     - 4.1
+     - 6.0
+     - ``sphinx.util.docstrings.separate_metadata()``
+
+   * - ``favicon`` variable in HTML templates
+     - 4.0
+     - TBD
+     - ``favicon_url``
+
+   * - ``logo`` variable in HTML templates
+     - 4.0
+     - TBD
+     - ``logo_url``
+
+   * - ``sphinx.directives.patches.ListTable``
+     - 4.0
+     - 6.0
+     - ``docutils.parsers.rst.directives.tables.ListSVTable``
+
+   * - ``sphinx.directives.patches.RSTTable``
+     - 4.0
+     - 6.0
+     - ``docutils.parsers.rst.directives.tables.RSTTable``
+
+   * - ``sphinx.ext.autodoc.directive.DocumenterBridge.filename_set``
+     - 4.0
+     - 6.0
+     - ``sphinx.ext.autodoc.directive.DocumenterBridge.record_dependencies``
+
+   * - ``sphinx.ext.autodoc.directive.DocumenterBridge.warn()``
+     - 4.0
+     - 6.0
+     - :ref:`logging-api`
+
+   * - ``sphinx.registry.SphinxComponentRegistry.get_source_input()``
+     - 4.0
+     - 6.0
+     - N/A
+
+   * - ``sphinx.registry.SphinxComponentRegistry.source_inputs``
+     - 4.0
+     - 6.0
+     - N/A
+
+   * - ``sphinx.transforms.FigureAligner``
+     - 4.0
+     - 6.0
+     - N/A
+
+   * - ``sphinx.util.pycompat.convert_with_2to3()``
+     - 4.0
+     - 6.0
+     - N/A
+
+   * - ``sphinx.util.pycompat.execfile_()``
+     - 4.0
+     - 6.0
+     - N/A
+
+   * - ``sphinx.util.smartypants``
+     - 4.0
+     - 6.0
+     - ``docutils.utils.smartquotes``
+
+   * - ``sphinx.util.typing.DirectiveOption``
+     - 4.0
+     - 6.0
+     - N/A
+
+   * - pending_xref node for viewcode extension
+     - 3.5
+     - 5.0
+     - ``sphinx.ext.viewcode.viewcode_anchor``
+
+   * - ``sphinx.builders.linkcheck.CheckExternalLinksBuilder.anchors_ignore``
+     - 3.5
+     - 5.0
+     - N/A
+
+   * - ``sphinx.builders.linkcheck.CheckExternalLinksBuilder.auth``
+     - 3.5
+     - 5.0
+     - N/A
+
+   * - ``sphinx.builders.linkcheck.CheckExternalLinksBuilder.broken``
+     - 3.5
+     - 5.0
+     - N/A
+
+   * - ``sphinx.builders.linkcheck.CheckExternalLinksBuilder.good``
+     - 3.5
+     - 5.0
+     - N/A
+
+   * - ``sphinx.builders.linkcheck.CheckExternalLinksBuilder.redirected``
+     - 3.5
+     - 5.0
+     - N/A
+
+   * - ``sphinx.builders.linkcheck.CheckExternalLinksBuilder.rqueue``
+     - 3.5
+     - 5.0
+     - N/A
+
+   * - ``sphinx.builders.linkcheck.CheckExternalLinksBuilder.to_ignore``
+     - 3.5
+     - 5.0
+     - N/A
+
+   * - ``sphinx.builders.linkcheck.CheckExternalLinksBuilder.workers``
+     - 3.5
+     - 5.0
+     - N/A
+
+   * - ``sphinx.builders.linkcheck.CheckExternalLinksBuilder.wqueue``
+     - 3.5
+     - 5.0
+     - N/A
+
+   * - ``sphinx.builders.linkcheck.node_line_or_0()``
+     - 3.5
+     - 5.0
+     - ``sphinx.util.nodes.get_node_line()``
+
+   * - ``sphinx.ext.autodoc.AttributeDocumenter.isinstanceattribute()``
+     - 3.5
+     - 5.0
+     - N/A
+
+   * - ``sphinx.ext.autodoc.importer.get_module_members()``
+     - 3.5
+     - 5.0
+     - ``sphinx.ext.autodoc.ModuleDocumenter.get_module_members()``
+
+   * - ``sphinx.ext.autosummary.generate._simple_info()``
+     - 3.5
+     - 5.0
+     - :ref:`logging-api`
+
+   * - ``sphinx.ext.autosummary.generate._simple_warn()``
+     - 3.5
+     - 5.0
+     - :ref:`logging-api`
+
+   * - ``sphinx.writers.html.HTMLTranslator.permalink_text``
+     - 3.5
+     - 5.0
+     - :confval:`html_permalinks_icon`
+
+   * - ``sphinx.writers.html5.HTML5Translator.permalink_text``
+     - 3.5
+     - 5.0
+     - :confval:`html_permalinks_icon`
+
+   * - The ``follow_wrapped`` argument of ``sphinx.util.inspect.signature()``
+     - 3.4
+     - 5.0
+     - N/A
+
+   * - The ``no_docstring`` argument of
+       ``sphinx.ext.autodoc.Documenter.add_content()``
+     - 3.4
+     - 5.0
+     - ``sphinx.ext.autodoc.Documenter.get_doc()``
+
+   * - ``sphinx.ext.autodoc.Documenter.get_object_members()``
+     - 3.4
+     - 6.0
+     - ``sphinx.ext.autodoc.ClassDocumenter.get_object_members()``
+
+   * - ``sphinx.ext.autodoc.DataDeclarationDocumenter``
+     - 3.4
+     - 5.0
+     - ``sphinx.ext.autodoc.DataDocumenter``
+
+   * - ``sphinx.ext.autodoc.GenericAliasDocumenter``
+     - 3.4
+     - 5.0
+     - ``sphinx.ext.autodoc.DataDocumenter``
+
+   * - ``sphinx.ext.autodoc.InstanceAttributeDocumenter``
+     - 3.4
+     - 5.0
+     - ``sphinx.ext.autodoc.AttributeDocumenter``
+
+   * - ``sphinx.ext.autodoc.SlotsAttributeDocumenter``
+     - 3.4
+     - 5.0
+     - ``sphinx.ext.autodoc.AttributeDocumenter``
+
+   * - ``sphinx.ext.autodoc.TypeVarDocumenter``
+     - 3.4
+     - 5.0
+     - ``sphinx.ext.autodoc.DataDocumenter``
+
+   * - ``sphinx.ext.autodoc.directive.DocumenterBridge.reporter``
+     - 3.5
+     - 5.0
+     - ``sphinx.util.logging``
+
+   * - ``sphinx.ext.autodoc.importer._getannotations()``
+     - 3.4
+     - 4.0
+     - ``sphinx.util.inspect.getannotations()``
+
+   * - ``sphinx.ext.autodoc.importer._getmro()``
+     - 3.4
+     - 4.0
+     - ``sphinx.util.inspect.getmro()``
+
+   * - ``sphinx.pycode.ModuleAnalyzer.parse()``
+     - 3.4
+     - 5.0
+     - ``sphinx.pycode.ModuleAnalyzer.analyze()``
+
+   * - ``sphinx.util.osutil.movefile()``
+     - 3.4
+     - 5.0
+     - ``os.replace()``
+
+   * - ``sphinx.util.requests.is_ssl_error()``
+     - 3.4
+     - 5.0
+     - N/A
+
+   * - ``sphinx.builders.latex.LaTeXBuilder.usepackages``
+     - 3.3
+     - 5.0
+     - N/A
+
+   * - ``sphinx.builders.latex.LaTeXBuilder.usepackages_afger_hyperref``
+     - 3.3
+     - 5.0
+     - N/A
+
+   * - ``sphinx.ext.autodoc.SingledispatchFunctionDocumenter``
+     - 3.3
+     - 5.0
+     - ``sphinx.ext.autodoc.FunctionDocumenter``
+
+   * - ``sphinx.ext.autodoc.SingledispatchMethodDocumenter``
+     - 3.3
+     - 5.0
+     - ``sphinx.ext.autodoc.MethodDocumenter``
+
+   * - ``sphinx.ext.autodoc.members_set_option()``
+     - 3.2
+     - 5.0
+     - N/A
+
+   * - ``sphinx.ext.autodoc.merge_special_members_option()``
+     - 3.2
+     - 5.0
+     - ``sphinx.ext.autodoc.merge_members_option()``
+
+   * - ``sphinx.writers.texinfo.TexinfoWriter.desc``
+     - 3.2
+     - 5.0
+     - ``sphinx.writers.texinfo.TexinfoWriter.descs``
+
+   * - The first argument for
+       ``sphinx.ext.autosummary.generate.AutosummaryRenderer`` has been changed
+       to Sphinx object
+     - 3.1
+     - 5.0
+     - N/A
+
+   * - ``sphinx.ext.autosummary.generate.AutosummaryRenderer`` takes an object
+       type as an argument
+     - 3.1
+     - 5.0
+     - N/A
+
+   * - The ``ignore`` argument of ``sphinx.ext.autodoc.Documenter.get_doc()``
+     - 3.1
+     - 5.0
+     - N/A
+
+   * - The ``template_dir`` argument of
+       ``sphinx.ext.autosummary.generate.AutosummaryRenderer``
+     - 3.1
+     - 5.0
+     - N/A
+
+   * - The ``module`` argument of
+       ``sphinx.ext.autosummary.generate.find_autosummary_in_docstring()``
+     - 3.0
+     - 5.0
+     - N/A
+
+   * - The ``builder`` argument of
+       ``sphinx.ext.autosummary.generate.generate_autosummary_docs()``
+     - 3.1
+     - 5.0
+     - N/A
+
+   * - The ``template_dir`` argument of
+       ``sphinx.ext.autosummary.generate.generate_autosummary_docs()``
+     - 3.1
+     - 5.0
+     - N/A
+
+   * - ``sphinx.ext.autosummary.generate.AutosummaryRenderer.exists()``
+     - 3.1
+     - 5.0
+     - N/A
+
+   * - The ``ignore`` argument of ``sphinx.util.docstring.prepare_docstring()``
+     - 3.1
+     - 5.0
+     - N/A
+
+   * - ``sphinx.util.rpartition()``
+     - 3.1
+     - 5.0
+     - ``str.rpartition()``
+
+   * - ``desc_signature['first']``
+     -
+     - 3.0
+     - N/A
+
+   * - ``sphinx.directives.DescDirective``
+     - 3.0
+     - 5.0
+     - ``sphinx.directives.ObjectDescription``
+
+   * - ``sphinx.domains.std.StandardDomain.add_object()``
+     - 3.0
+     - 5.0
+     - ``sphinx.domains.std.StandardDomain.note_object()``
+
+   * - ``sphinx.domains.python.PyDecoratorMixin``
+     - 3.0
+     - 5.0
+     - N/A
+
+   * - ``sphinx.ext.autodoc.get_documenters()``
+     - 3.0
+     - 5.0
+     - ``sphinx.registry.documenters``
+
+   * - ``sphinx.ext.autosummary.process_autosummary_toc()``
+     - 3.0
+     - 5.0
+     - N/A
+
+   * - ``sphinx.parsers.Parser.app``
+     - 3.0
+     - 5.0
+     - N/A
+
+   * - ``sphinx.testing.path.Path.text()``
+     - 3.0
+     - 5.0
+     - ``sphinx.testing.path.Path.read_text()``
+
+   * - ``sphinx.testing.path.Path.bytes()``
+     - 3.0
+     - 5.0
+     - ``sphinx.testing.path.Path.read_bytes()``
+
+   * - ``sphinx.util.inspect.getargspec()``
+     - 3.0
+     - 5.0
+     - ``inspect.getargspec()``
+
+   * - ``sphinx.writers.latex.LaTeXWriter.format_docclass()``
+     - 3.0
+     - 5.0
+     - LaTeX Themes
+
+   * - ``decode`` argument of ``sphinx.pycode.ModuleAnalyzer()``
+     - 2.4
+     - 4.0
+     - N/A
+
+   * - ``sphinx.directives.other.Index``
+     - 2.4
+     - 4.0
+     - ``sphinx.domains.index.IndexDirective``
+
+   * - ``sphinx.environment.temp_data['gloss_entries']``
+     - 2.4
+     - 4.0
+     - ``documents.nameids``
+
+   * - ``sphinx.environment.BuildEnvironment.indexentries``
+     - 2.4
+     - 4.0
+     - ``sphinx.domains.index.IndexDomain``
+
+   * - ``sphinx.environment.collectors.indexentries.IndexEntriesCollector``
+     - 2.4
+     - 4.0
+     - ``sphinx.domains.index.IndexDomain``
+
+   * - ``sphinx.io.FiletypeNotFoundError``
+     - 2.4
+     - 4.0
+     - ``sphinx.errors.FiletypeNotFoundError``
+
+   * - ``sphinx.ext.apidoc.INITPY``
+     - 2.4
+     - 4.0
+     - N/A
+
+   * - ``sphinx.ext.apidoc.shall_skip()``
+     - 2.4
+     - 4.0
+     - ``sphinx.ext.apidoc.is_skipped_package``
+
+   * - ``sphinx.io.get_filetype()``
+     - 2.4
+     - 4.0
+     - ``sphinx.util.get_filetype()``
+
+   * - ``sphinx.pycode.ModuleAnalyzer.encoding``
+     - 2.4
+     - 4.0
+     - N/A
+
+   * - ``sphinx.roles.Index``
+     - 2.4
+     - 4.0
+     - ``sphinx.domains.index.IndexRole``
+
+   * - ``sphinx.util.detect_encoding()``
+     - 2.4
+     - 4.0
+     - ``tokenize.detect_encoding()``
+
+   * - ``sphinx.util.get_module_source()``
+     - 2.4
+     - 4.0
+     - N/A
+
+   * - ``sphinx.util.inspect.Signature``
+     - 2.4
+     - 4.0
+     - ``sphinx.util.inspect.signature`` and
+       ``sphinx.util.inspect.stringify_signature()``
+
+   * - ``sphinx.util.inspect.safe_getmembers()``
+     - 2.4
+     - 4.0
+     - ``inspect.getmembers()``
+
+   * - ``sphinx.writers.latex.LaTeXTranslator.settings.author``
+     - 2.4
+     - 4.0
+     - N/A
+
+   * - ``sphinx.writers.latex.LaTeXTranslator.settings.contentsname``
+     - 2.4
+     - 4.0
+     - ``document['contentsname']``
+
+   * - ``sphinx.writers.latex.LaTeXTranslator.settings.docclass``
+     - 2.4
+     - 4.0
+     - ``document['docclass']``
+
+   * - ``sphinx.writers.latex.LaTeXTranslator.settings.docname``
+     - 2.4
+     - 4.0
+     - N/A
+
+   * - ``sphinx.writers.latex.LaTeXTranslator.settings.title``
+     - 2.4
+     - 4.0
+     - N/A
+
+   * - ``sphinx.writers.latex.ADDITIONAL_SETTINGS``
+     - 2.4
+     - 4.0
+     - ``sphinx.builders.latex.constants.ADDITIONAL_SETTINGS``
+
+   * - ``sphinx.writers.latex.DEFAULT_SETTINGS``
+     - 2.4
+     - 4.0
+     - ``sphinx.builders.latex.constants.DEFAULT_SETTINGS``
+
+   * - ``sphinx.writers.latex.LUALATEX_DEFAULT_FONTPKG``
+     - 2.4
+     - 4.0
+     - ``sphinx.builders.latex.constants.LUALATEX_DEFAULT_FONTPKG``
+
+   * - ``sphinx.writers.latex.PDFLATEX_DEFAULT_FONTPKG``
+     - 2.4
+     - 4.0
+     - ``sphinx.builders.latex.constants.PDFLATEX_DEFAULT_FONTPKG``
+
+   * - ``sphinx.writers.latex.XELATEX_DEFAULT_FONTPKG``
+     - 2.4
+     - 4.0
+     - ``sphinx.builders.latex.constants.XELATEX_DEFAULT_FONTPKG``
+
+   * - ``sphinx.writers.latex.XELATEX_GREEK_DEFAULT_FONTPKG``
+     - 2.4
+     - 4.0
+     - ``sphinx.builders.latex.constants.XELATEX_GREEK_DEFAULT_FONTPKG``
+
+   * - ``sphinx.builders.gettext.POHEADER``
+     - 2.3
+     - 4.0
+     - ``sphinx/templates/gettext/message.pot_t`` (template file)
+
+   * - ``sphinx.io.SphinxStandaloneReader.app``
+     - 2.3
+     - 4.0
+     - ``sphinx.io.SphinxStandaloneReader.setup()``
+
+   * - ``sphinx.io.SphinxStandaloneReader.env``
+     - 2.3
+     - 4.0
+     - ``sphinx.io.SphinxStandaloneReader.setup()``
+
+   * - ``sphinx.util.texescape.tex_escape_map``
+     - 2.3
+     - 4.0
+     - ``sphinx.util.texescape.escape()``
+
+   * - ``sphinx.util.texescape.tex_hl_escape_map_new``
+     - 2.3
+     - 4.0
+     - ``sphinx.util.texescape.hlescape()``
+
+   * - ``sphinx.writers.latex.LaTeXTranslator.no_contractions``
+     - 2.3
+     - 4.0
+     - N/A
+
+   * - ``sphinx.domains.math.MathDomain.add_equation()``
+     - 2.2
+     - 4.0
+     - ``sphinx.domains.math.MathDomain.note_equation()``
+
+   * - ``sphinx.domains.math.MathDomain.get_next_equation_number()``
+     - 2.2
+     - 4.0
+     - ``sphinx.domains.math.MathDomain.note_equation()``
+
+   * - The ``info`` and ``warn`` arguments of
+       ``sphinx.ext.autosummary.generate.generate_autosummary_docs()``
+     - 2.2
+     - 4.0
+     - ``logging.info()`` and ``logging.warning()``
+
+   * - ``sphinx.ext.autosummary.generate._simple_info()``
+     - 2.2
+     - 4.0
+     - ``logging.info()``
+
+   * - ``sphinx.ext.autosummary.generate._simple_warn()``
+     - 2.2
+     - 4.0
+     - ``logging.warning()``
+
+   * - ``sphinx.ext.todo.merge_info()``
+     - 2.2
+     - 4.0
+     - ``sphinx.ext.todo.TodoDomain``
+
+   * - ``sphinx.ext.todo.process_todo_nodes()``
+     - 2.2
+     - 4.0
+     - ``sphinx.ext.todo.TodoDomain``
+
+   * - ``sphinx.ext.todo.process_todos()``
+     - 2.2
+     - 4.0
+     - ``sphinx.ext.todo.TodoDomain``
+
+   * - ``sphinx.ext.todo.purge_todos()``
+     - 2.2
+     - 4.0
+     - ``sphinx.ext.todo.TodoDomain``
+
+   * - ``sphinx.builders.latex.LaTeXBuilder.apply_transforms()``
+     - 2.1
+     - 4.0
+     - N/A
+
+   * - ``sphinx.builders._epub_base.EpubBuilder.esc()``
+     - 2.1
+     - 4.0
+     - ``html.escape()``
+
+   * - ``sphinx.directives.Acks``
+     - 2.1
+     - 4.0
+     - ``sphinx.directives.other.Acks``
+
+   * - ``sphinx.directives.Author``
+     - 2.1
+     - 4.0
+     - ``sphinx.directives.other.Author``
+
+   * - ``sphinx.directives.Centered``
+     - 2.1
+     - 4.0
+     - ``sphinx.directives.other.Centered``
+
+   * - ``sphinx.directives.Class``
+     - 2.1
+     - 4.0
+     - ``sphinx.directives.other.Class``
+
+   * - ``sphinx.directives.CodeBlock``
+     - 2.1
+     - 4.0
+     - ``sphinx.directives.code.CodeBlock``
+
+   * - ``sphinx.directives.Figure``
+     - 2.1
+     - 4.0
+     - ``sphinx.directives.patches.Figure``
+
+   * - ``sphinx.directives.HList``
+     - 2.1
+     - 4.0
+     - ``sphinx.directives.other.HList``
+
+   * - ``sphinx.directives.Highlight``
+     - 2.1
+     - 4.0
+     - ``sphinx.directives.code.Highlight``
+
+   * - ``sphinx.directives.Include``
+     - 2.1
+     - 4.0
+     - ``sphinx.directives.other.Include``
+
+   * - ``sphinx.directives.Index``
+     - 2.1
+     - 4.0
+     - ``sphinx.directives.other.Index``
+
+   * - ``sphinx.directives.LiteralInclude``
+     - 2.1
+     - 4.0
+     - ``sphinx.directives.code.LiteralInclude``
+
+   * - ``sphinx.directives.Meta``
+     - 2.1
+     - 4.0
+     - ``sphinx.directives.patches.Meta``
+
+   * - ``sphinx.directives.Only``
+     - 2.1
+     - 4.0
+     - ``sphinx.directives.other.Only``
+
+   * - ``sphinx.directives.SeeAlso``
+     - 2.1
+     - 4.0
+     - ``sphinx.directives.other.SeeAlso``
+
+   * - ``sphinx.directives.TabularColumns``
+     - 2.1
+     - 4.0
+     - ``sphinx.directives.other.TabularColumns``
+
+   * - ``sphinx.directives.TocTree``
+     - 2.1
+     - 4.0
+     - ``sphinx.directives.other.TocTree``
+
+   * - ``sphinx.directives.VersionChange``
+     - 2.1
+     - 4.0
+     - ``sphinx.directives.other.VersionChange``
+
+   * - ``sphinx.domains.python.PyClassmember``
+     - 2.1
+     - 4.0
+     - ``sphinx.domains.python.PyAttribute``,
+       ``sphinx.domains.python.PyMethod``,
+       ``sphinx.domains.python.PyClassMethod``,
+       ``sphinx.domains.python.PyObject`` and
+       ``sphinx.domains.python.PyStaticMethod``
+
+   * - ``sphinx.domains.python.PyModulelevel``
+     - 2.1
+     - 4.0
+     - ``sphinx.domains.python.PyFunction``,
+       ``sphinx.domains.python.PyObject`` and
+       ``sphinx.domains.python.PyVariable``
+
+   * - ``sphinx.domains.std.StandardDomain._resolve_citation_xref()``
+     - 2.1
+     - 4.0
+     - ``sphinx.domains.citation.CitationDomain.resolve_xref()``
+
+   * - ``sphinx.domains.std.StandardDomain.note_citations()``
+     - 2.1
+     - 4.0
+     - ``sphinx.domains.citation.CitationDomain.note_citation()``
+
+   * - ``sphinx.domains.std.StandardDomain.note_citation_refs()``
+     - 2.1
+     - 4.0
+     - ``sphinx.domains.citation.CitationDomain.note_citation_reference()``
+
+   * - ``sphinx.domains.std.StandardDomain.note_labels()``
+     - 2.1
+     - 4.0
+     - ``sphinx.domains.std.StandardDomain.process_doc()``
+
+   * - ``sphinx.domains.js.JSObject.display_prefix``
+     -
+     - 4.3
+     - ``sphinx.domains.js.JSObject.get_display_prefix()``
+
+   * - ``sphinx.environment.NoUri``
+     - 2.1
+     - 3.0
+     - ``sphinx.errors.NoUri``
+
+   * - ``sphinx.ext.apidoc.format_directive()``
+     - 2.1
+     - 4.0
+     - N/A
+
+   * - ``sphinx.ext.apidoc.format_heading()``
+     - 2.1
+     - 4.0
+     - N/A
+
+   * - ``sphinx.ext.apidoc.makename()``
+     - 2.1
+     - 4.0
+     - ``sphinx.ext.apidoc.module_join()``
+
+   * - ``sphinx.ext.autodoc.importer.MockFinder``
+     - 2.1
+     - 4.0
+     - ``sphinx.ext.autodoc.mock.MockFinder``
+
+   * - ``sphinx.ext.autodoc.importer.MockLoader``
+     - 2.1
+     - 4.0
+     - ``sphinx.ext.autodoc.mock.MockLoader``
+
+   * - ``sphinx.ext.autodoc.importer.mock()``
+     - 2.1
+     - 4.0
+     - ``sphinx.ext.autodoc.mock.mock()``
+
+   * - ``sphinx.ext.autosummary.autolink_role()``
+     - 2.1
+     - 4.0
+     - ``sphinx.ext.autosummary.AutoLink``
+
+   * - ``sphinx.ext.imgmath.DOC_BODY``
+     - 2.1
+     - 4.0
+     - N/A
+
+   * - ``sphinx.ext.imgmath.DOC_BODY_PREVIEW``
+     - 2.1
+     - 4.0
+     - N/A
+
+   * - ``sphinx.ext.imgmath.DOC_HEAD``
+     - 2.1
+     - 4.0
+     - N/A
+
+   * - ``sphinx.transforms.CitationReferences``
+     - 2.1
+     - 4.0
+     - ``sphinx.domains.citation.CitationReferenceTransform``
+
+   * - ``sphinx.transforms.SmartQuotesSkipper``
+     - 2.1
+     - 4.0
+     - ``sphinx.domains.citation.CitationDefinitionTransform``
+
+   * - ``sphinx.util.docfields.DocFieldTransformer.preprocess_fieldtypes()``
+     - 2.1
+     - 4.0
+     - ``sphinx.directives.ObjectDescription.get_field_type_map()``
+
+   * - ``sphinx.util.node.find_source_node()``
+     - 2.1
+     - 4.0
+     - ``sphinx.util.node.get_node_source()``
+
+   * - ``sphinx.util.i18n.find_catalog()``
+     - 2.1
+     - 4.0
+     - ``sphinx.util.i18n.docname_to_domain()``
+
+   * - ``sphinx.util.i18n.find_catalog_files()``
+     - 2.1
+     - 4.0
+     - ``sphinx.util.i18n.CatalogRepository``
+
+   * - ``sphinx.util.i18n.find_catalog_source_files()``
+     - 2.1
+     - 4.0
+     - ``sphinx.util.i18n.CatalogRepository``
+
+   * - ``encoding`` argument of ``autodoc.Documenter.get_doc()``,
+       ``autodoc.DocstringSignatureMixin.get_doc()``,
+       ``autodoc.DocstringSignatureMixin._find_signature()``, and
+       ``autodoc.ClassDocumenter.get_doc()``
+     - 2.0
+     - 4.0
+     - N/A
+
+   * - arguments of ``EpubBuilder.build_mimetype()``,
+       ``EpubBuilder.build_container()``, ``EpubBuilder.build_content()``,
+       ``EpubBuilder.build_toc()`` and ``EpubBuilder.build_epub()``
+     - 2.0
+     - 4.0
+     - N/A
+
+   * - arguments of ``Epub3Builder.build_navigation_doc()``
+     - 2.0
+     - 4.0
+     - N/A
+
+   * - ``nodetype`` argument of
+       ``sphinx.search.WordCollector.is_meta_keywords()``
+     - 2.0
+     - 4.0
+     - N/A
+
+   * - ``suffix`` argument of ``BuildEnvironment.doc2path()``
+     - 2.0
+     - 4.0
+     - N/A
+
+   * - string style ``base`` argument of ``BuildEnvironment.doc2path()``
+     - 2.0
+     - 4.0
+     - ``os.path.join()``
+
+   * - ``sphinx.addnodes.abbreviation``
+     - 2.0
+     - 4.0
+     - ``docutils.nodes.abbreviation``
+
+   * - ``sphinx.builders.applehelp``
+     - 2.0
+     - 4.0
+     - ``sphinxcontrib.applehelp``
+
+   * - ``sphinx.builders.devhelp``
+     - 2.0
+     - 4.0
+     - ``sphinxcontrib.devhelp``
+
+   * - ``sphinx.builders.epub3.Epub3Builder.validate_config_value()``
+     - 2.0
+     - 4.0
+     - ``sphinx.builders.epub3.validate_config_values()``
+
+   * - ``sphinx.builders.html.JSONHTMLBuilder``
+     - 2.0
+     - 4.0
+     - ``sphinx.builders.serializinghtml.JSONHTMLBuilder``
+
+   * - ``sphinx.builders.html.PickleHTMLBuilder``
+     - 2.0
+     - 4.0
+     - ``sphinx.builders.serializinghtml.PickleHTMLBuilder``
+
+   * - ``sphinx.builders.html.SerializingHTMLBuilder``
+     - 2.0
+     - 4.0
+     - ``sphinx.builders.serializinghtml.SerializingHTMLBuilder``
+
+   * - ``sphinx.builders.html.SingleFileHTMLBuilder``
+     - 2.0
+     - 4.0
+     - ``sphinx.builders.singlehtml.SingleFileHTMLBuilder``
+
+   * - ``sphinx.builders.html.WebHTMLBuilder``
+     - 2.0
+     - 4.0
+     - ``sphinx.builders.serializinghtml.PickleHTMLBuilder``
+
+   * - ``sphinx.builders.htmlhelp``
+     - 2.0
+     - 4.0
+     - ``sphinxcontrib.htmlhelp``
+
+   * - ``sphinx.builders.htmlhelp.HTMLHelpBuilder.open_file()``
+     - 2.0
+     - 4.0
+     - ``open()``
+
+   * - ``sphinx.builders.qthelp``
+     - 2.0
+     - 4.0
+     - ``sphinxcontrib.qthelp``
+
+   * - ``sphinx.cmd.quickstart.term_decode()``
+     - 2.0
+     - 4.0
+     - N/A
+
+   * - ``sphinx.cmd.quickstart.TERM_ENCODING``
+     - 2.0
+     - 4.0
+     - ``sys.stdin.encoding``
+
+   * - ``sphinx.config.check_unicode()``
+     - 2.0
+     - 4.0
+     - N/A
+
+   * - ``sphinx.config.string_classes``
+     - 2.0
+     - 4.0
+     - ``[str]``
+
+   * - ``sphinx.domains.cpp.DefinitionError.description``
+     - 2.0
+     - 4.0
+     - ``str(exc)``
+
+   * - ``sphinx.domains.cpp.NoOldIdError.description``
+     - 2.0
+     - 4.0
+     - ``str(exc)``
+
+   * - ``sphinx.domains.cpp.UnsupportedMultiCharacterCharLiteral.decoded``
+     - 2.0
+     - 4.0
+     - ``str(exc)``
+
+   * - ``sphinx.ext.autosummary.Autosummary.warn()``
+     - 2.0
+     - 4.0
+     - N/A
+
+   * - ``sphinx.ext.autosummary.Autosummary.genopt``
+     - 2.0
+     - 4.0
+     - N/A
+
+   * - ``sphinx.ext.autosummary.Autosummary.warnings``
+     - 2.0
+     - 4.0
+     - N/A
+
+   * - ``sphinx.ext.autosummary.Autosummary.result``
+     - 2.0
+     - 4.0
+     - N/A
+
+   * - ``sphinx.ext.doctest.doctest_encode()``
+     - 2.0
+     - 4.0
+     - N/A
+
+   * - ``sphinx.ext.jsmath``
+     - 2.0
+     - 4.0
+     - ``sphinxcontrib.jsmath``
+
+   * - ``sphinx.roles.abbr_role()``
+     - 2.0
+     - 4.0
+     - ``sphinx.roles.Abbreviation``
+
+   * - ``sphinx.roles.emph_literal_role()``
+     - 2.0
+     - 4.0
+     - ``sphinx.roles.EmphasizedLiteral``
+
+   * - ``sphinx.roles.menusel_role()``
+     - 2.0
+     - 4.0
+     - ``sphinx.roles.GUILabel`` or ``sphinx.roles.MenuSelection``
+
+   * - ``sphinx.roles.index_role()``
+     - 2.0
+     - 4.0
+     - ``sphinx.roles.Index``
+
+   * - ``sphinx.roles.indexmarkup_role()``
+     - 2.0
+     - 4.0
+     - ``sphinx.roles.PEP`` or ``sphinx.roles.RFC``
+
+   * - ``sphinx.testing.util.remove_unicode_literal()``
+     - 2.0
+     - 4.0
+     - N/A
+
+   * - ``sphinx.util.attrdict``
+     - 2.0
+     - 4.0
+     - N/A
+
+   * - ``sphinx.util.force_decode()``
+     - 2.0
+     - 5.0
+     - N/A
+
+   * - ``sphinx.util.get_matching_docs()``
+     - 2.0
+     - 4.0
+     - ``sphinx.util.get_matching_files()``
+
+   * - ``sphinx.util.inspect.Parameter``
+     - 2.0
+     - 3.0
+     - N/A
+
+   * - ``sphinx.util.jsonimpl``
+     - 2.0
+     - 4.0
+     - ``sphinxcontrib.serializinghtml.jsonimpl``
+
+   * - ``sphinx.util.osutil.EEXIST``
+     - 2.0
+     - 4.0
+     - ``errno.EEXIST`` or ``FileExistsError``
+
+   * - ``sphinx.util.osutil.EINVAL``
+     - 2.0
+     - 4.0
+     - ``errno.EINVAL``
+
+   * - ``sphinx.util.osutil.ENOENT``
+     - 2.0
+     - 4.0
+     - ``errno.ENOENT`` or ``FileNotFoundError``
+
+   * - ``sphinx.util.osutil.EPIPE``
+     - 2.0
+     - 4.0
+     - ``errno.ENOENT`` or ``BrokenPipeError``
+
+   * - ``sphinx.util.osutil.walk()``
+     - 2.0
+     - 4.0
+     - ``os.walk()``
+
+   * - ``sphinx.util.pycompat.NoneType``
+     - 2.0
+     - 4.0
+     - ``sphinx.util.typing.NoneType``
+
+   * - ``sphinx.util.pycompat.TextIOWrapper``
+     - 2.0
+     - 4.0
+     - ``io.TextIOWrapper``
+
+   * - ``sphinx.util.pycompat.UnicodeMixin``
+     - 2.0
+     - 4.0
+     - N/A
+
+   * - ``sphinx.util.pycompat.htmlescape()``
+     - 2.0
+     - 4.0
+     - ``html.escape()``
+
+   * - ``sphinx.util.pycompat.indent()``
+     - 2.0
+     - 4.0
+     - ``textwrap.indent()``
+
+   * - ``sphinx.util.pycompat.sys_encoding``
+     - 2.0
+     - 4.0
+     - ``sys.getdefaultencoding()``
+
+   * - ``sphinx.util.pycompat.terminal_safe()``
+     - 2.0
+     - 4.0
+     - ``sphinx.util.console.terminal_safe()``
+
+   * - ``sphinx.util.pycompat.u``
+     - 2.0
+     - 4.0
+     - N/A
+
+   * - ``sphinx.util.PeekableIterator``
+     - 2.0
+     - 4.0
+     - N/A
+
+   * - Omitting the ``filename`` argument in an overriddent
+       ``IndexBuilder.feed()`` method.
+     - 2.0
+     - 4.0
+     - ``IndexBuilder.feed(docname, filename, title, doctree)``
+
+   * - ``sphinx.writers.latex.ExtBabel``
+     - 2.0
+     - 4.0
+     - ``sphinx.builders.latex.util.ExtBabel``
+
+   * - ``sphinx.writers.latex.LaTeXTranslator.babel_defmacro()``
+     - 2.0
+     - 4.0
+     - N/A
+
+   * - ``sphinx.application.Sphinx._setting_up_extension``
+     - 2.0
+     - 3.0
+     - N/A
+
+   * - The ``importer`` argument of ``sphinx.ext.autodoc.importer._MockModule``
+     - 2.0
+     - 3.0
+     - N/A
+
+   * - ``sphinx.ext.autodoc.importer._MockImporter``
+     - 2.0
+     - 3.0
+     - N/A
+
+   * - ``sphinx.io.SphinxBaseFileInput``
+     - 2.0
+     - 3.0
+     - N/A
+
+   * - ``sphinx.io.SphinxFileInput.supported``
+     - 2.0
+     - 3.0
+     - N/A
+
+   * - ``sphinx.io.SphinxRSTFileInput``
+     - 2.0
+     - 3.0
+     - N/A
+
+   * - ``sphinx.registry.SphinxComponentRegistry.add_source_input()``
+     - 2.0
+     - 3.0
+     - N/A
+
+   * - ``sphinx.writers.latex.LaTeXTranslator._make_visit_admonition()``
+     - 2.0
+     - 3.0
+     - N/A
+
+   * - ``sphinx.writers.latex.LaTeXTranslator.collect_footnotes()``
+     - 2.0
+     - 4.0
+     - N/A
+
+   * - ``sphinx.writers.texinfo.TexinfoTranslator._make_visit_admonition()``
+     - 2.0
+     - 3.0
+     - N/A
+
+   * - ``sphinx.writers.text.TextTranslator._make_depart_admonition()``
+     - 2.0
+     - 3.0
+     - N/A
+
+   * - ``sphinx.writers.latex.LaTeXTranslator.generate_numfig_format()``
+     - 2.0
+     - 4.0
+     - N/A
+
+   * - :rst:dir:`highlightlang`
+     - 1.8
+     - 4.0
+     - :rst:dir:`highlight`
+
+   * - :meth:`~sphinx.application.Sphinx.add_stylesheet()`
+     - 1.8
+     - 6.0
+     - :meth:`~sphinx.application.Sphinx.add_css_file()`
+
+   * - :meth:`~sphinx.application.Sphinx.add_javascript()`
+     - 1.8
+     - 4.0
+     - :meth:`~sphinx.application.Sphinx.add_js_file()`
+
+   * - :confval:`autodoc_default_flags`
+     - 1.8
+     - 4.0
+     - :confval:`autodoc_default_options`
+
+   * - ``content`` arguments of ``sphinx.util.image.guess_mimetype()``
+     - 1.8
+     - 3.0
+     - N/A
+
+   * - ``gettext_compact`` arguments of
+       ``sphinx.util.i18n.find_catalog_source_files()``
+     - 1.8
+     - 3.0
+     - N/A
+
+   * - ``sphinx.io.SphinxI18nReader.set_lineno_for_reporter()``
+     - 1.8
+     - 3.0
+     - N/A
+
+   * - ``sphinx.io.SphinxI18nReader.line``
+     - 1.8
+     - 3.0
+     - N/A
+
+   * - ``sphinx.directives.other.VersionChanges``
+     - 1.8
+     - 3.0
+     - ``sphinx.domains.changeset.VersionChanges``
+
+   * - ``sphinx.highlighting.PygmentsBridge.unhighlight()``
+     - 1.8
+     - 3.0
+     - N/A
+
+   * - ``trim_doctest_flags`` arguments of
+       ``sphinx.highlighting.PygmentsBridge``
+     - 1.8
+     - 3.0
+     - N/A
+
+   * - ``sphinx.ext.mathbase``
+     - 1.8
+     - 3.0
+     - N/A
+
+   * - ``sphinx.ext.mathbase.MathDomain``
+     - 1.8
+     - 3.0
+     - ``sphinx.domains.math.MathDomain``
+
+   * - ``sphinx.ext.mathbase.MathDirective``
+     - 1.8
+     - 3.0
+     - ``sphinx.directives.patches.MathDirective``
+
+   * - ``sphinx.ext.mathbase.math_role()``
+     - 1.8
+     - 3.0
+     - ``docutils.parsers.rst.roles.math_role()``
+
+   * - ``sphinx.ext.mathbase.setup_math()``
+     - 1.8
+     - 3.0
+     - :meth:`~sphinx.application.Sphinx.add_html_math_renderer()`
+
+   * - ``sphinx.ext.mathbase.is_in_section_title()``
+     - 1.8
+     - 3.0
+     - N/A
+
+   * - ``sphinx.ext.mathbase.get_node_equation_number()``
+     - 1.8
+     - 3.0
+     - ``sphinx.util.math.get_node_equation_number()``
+
+   * - ``sphinx.ext.mathbase.wrap_displaymath()``
+     - 1.8
+     - 3.0
+     - ``sphinx.util.math.wrap_displaymath()``
+
+   * - ``sphinx.ext.mathbase.math`` (node)
+     - 1.8
+     - 3.0
+     - ``docutils.nodes.math``
+
+   * - ``sphinx.ext.mathbase.displaymath`` (node)
+     - 1.8
+     - 3.0
+     - ``docutils.nodes.math_block``
+
+   * - ``sphinx.ext.mathbase.eqref`` (node)
+     - 1.8
+     - 3.0
+     - ``sphinx.builders.latex.nodes.math_reference``
+
+   * - ``viewcode_import`` (config value)
+     - 1.8
+     - 3.0
+     - :confval:`viewcode_follow_imported_members`
+
+   * - ``sphinx.writers.latex.Table.caption_footnotetexts``
+     - 1.8
+     - 3.0
+     - N/A
+
+   * - ``sphinx.writers.latex.Table.header_footnotetexts``
+     - 1.8
+     - 3.0
+     - N/A
+
+   * - ``sphinx.writers.latex.LaTeXTranslator.footnotestack``
+     - 1.8
+     - 3.0
+     - N/A
+
+   * - ``sphinx.writers.latex.LaTeXTranslator.in_container_literal_block``
+     - 1.8
+     - 3.0
+     - N/A
+
+   * - ``sphinx.writers.latex.LaTeXTranslator.next_section_ids``
+     - 1.8
+     - 3.0
+     - N/A
+
+   * - ``sphinx.writers.latex.LaTeXTranslator.next_hyperlink_ids``
+     - 1.8
+     - 3.0
+     - N/A
+
+   * - ``sphinx.writers.latex.LaTeXTranslator.restrict_footnote()``
+     - 1.8
+     - 3.0
+     - N/A
+
+   * - ``sphinx.writers.latex.LaTeXTranslator.unrestrict_footnote()``
+     - 1.8
+     - 3.0
+     - N/A
+
+   * - ``sphinx.writers.latex.LaTeXTranslator.push_hyperlink_ids()``
+     - 1.8
+     - 3.0
+     - N/A
+
+   * - ``sphinx.writers.latex.LaTeXTranslator.pop_hyperlink_ids()``
+     - 1.8
+     - 3.0
+     - N/A
+
+   * - ``sphinx.writers.latex.LaTeXTranslator.bibitems``
+     - 1.8
+     - 3.0
+     - N/A
+
+   * - ``sphinx.writers.latex.LaTeXTranslator.hlsettingstack``
+     - 1.8
+     - 3.0
+     - N/A
+
+   * - ``sphinx.writers.latex.ExtBabel.get_shorthandoff()``
+     - 1.8
+     - 3.0
+     - N/A
+
+   * - ``sphinx.writers.html.HTMLTranslator.highlightlang()``
+     - 1.8
+     - 3.0
+     - N/A
+
+   * - ``sphinx.writers.html.HTMLTranslator.highlightlang_base()``
+     - 1.8
+     - 3.0
+     - N/A
+
+   * - ``sphinx.writers.html.HTMLTranslator.highlightlangopts()``
+     - 1.8
+     - 3.0
+     - N/A
+
+   * - ``sphinx.writers.html.HTMLTranslator.highlightlinenothreshold()``
+     - 1.8
+     - 3.0
+     - N/A
+
+   * - ``sphinx.writers.html5.HTMLTranslator.highlightlang()``
+     - 1.8
+     - 3.0
+     - N/A
+
+   * - ``sphinx.writers.html5.HTMLTranslator.highlightlang_base()``
+     - 1.8
+     - 3.0
+     - N/A
+
+   * - ``sphinx.writers.html5.HTMLTranslator.highlightlangopts()``
+     - 1.8
+     - 3.0
+     - N/A
+
+   * - ``sphinx.writers.html5.HTMLTranslator.highlightlinenothreshold()``
+     - 1.8
+     - 3.0
+     - N/A
+
+   * - ``sphinx.writers.latex.LaTeXTranslator.check_latex_elements()``
+     - 1.8
+     - 3.0
+     - Nothing
+
+   * - ``sphinx.application.CONFIG_FILENAME``
+     - 1.8
+     - 3.0
+     - ``sphinx.config.CONFIG_FILENAME``
+
+   * - ``Config.check_unicode()``
+     - 1.8
+     - 3.0
+     - ``sphinx.config.check_unicode()``
+
+   * - ``Config.check_types()``
+     - 1.8
+     - 3.0
+     - ``sphinx.config.check_confval_types()``
+
+   * - ``dirname``, ``filename`` and ``tags`` arguments of
+       ``Config.__init__()``
+     - 1.8
+     - 3.0
+     - ``Config.read()``
+
+   * - The value of :confval:`html_search_options`
+     - 1.8
+     - 3.0
+     - see :confval:`html_search_options`
+
+   * - ``sphinx.versioning.prepare()``
+     - 1.8
+     - 3.0
+     - ``sphinx.versioning.UIDTransform``
+
+   * - ``Sphinx.override_domain()``
+     - 1.8
+     - 3.0
+     - :meth:`~sphinx.application.Sphinx.add_domain()`
+
+   * - ``Sphinx.import_object()``
+     - 1.8
+     - 3.0
+     - ``sphinx.util.import_object()``
+
+   * - ``suffix`` argument of
+       :meth:`~sphinx.application.Sphinx.add_source_parser()`
+     - 1.8
+     - 3.0
+     - :meth:`~sphinx.application.Sphinx.add_source_suffix()`
+
+
+   * - ``BuildEnvironment.load()``
+     - 1.8
+     - 3.0
+     - ``pickle.load()``
+
+   * - ``BuildEnvironment.loads()``
+     - 1.8
+     - 3.0
+     - ``pickle.loads()``
+
+   * - ``BuildEnvironment.frompickle()``
+     - 1.8
+     - 3.0
+     - ``pickle.load()``
+
+   * - ``BuildEnvironment.dump()``
+     - 1.8
+     - 3.0
+     - ``pickle.dump()``
+
+   * - ``BuildEnvironment.dumps()``
+     - 1.8
+     - 3.0
+     - ``pickle.dumps()``
+
+   * - ``BuildEnvironment.topickle()``
+     - 1.8
+     - 3.0
+     - ``pickle.dump()``
+
+   * - ``BuildEnvironment._nitpick_ignore``
+     - 1.8
+     - 3.0
+     - :confval:`nitpick_ignore`
+
+   * - ``BuildEnvironment.versionchanges``
+     - 1.8
+     - 3.0
+     - N/A
+
+   * - ``BuildEnvironment.update()``
+     - 1.8
+     - 3.0
+     - ``Builder.read()``
+
+   * - ``BuildEnvironment.read_doc()``
+     - 1.8
+     - 3.0
+     - ``Builder.read_doc()``
+
+   * - ``BuildEnvironment._read_serial()``
+     - 1.8
+     - 3.0
+     - ``Builder.read()``
+
+   * - ``BuildEnvironment._read_parallel()``
+     - 1.8
+     - 3.0
+     - ``Builder.read()``
+
+   * - ``BuildEnvironment.write_doctree()``
+     - 1.8
+     - 3.0
+     - ``Builder.write_doctree()``
+
+   * - ``BuildEnvironment.note_versionchange()``
+     - 1.8
+     - 3.0
+     - ``ChangesDomain.note_changeset()``
+
+   * - ``warn()`` (template helper function)
+     - 1.8
+     - 3.0
+     - ``warning()``
+
+   * - :confval:`source_parsers`
+     - 1.8
+     - 3.0
+     - :meth:`~sphinx.application.Sphinx.add_source_parser()`
+
+   * - ``sphinx.util.docutils.directive_helper()``
+     - 1.8
+     - 3.0
+     - ``Directive`` class of docutils
+
+   * - ``sphinx.cmdline``
+     - 1.8
+     - 3.0
+     - ``sphinx.cmd.build``
+
+   * - ``sphinx.make_mode``
+     - 1.8
+     - 3.0
+     - ``sphinx.cmd.make_mode``
+
+   * - ``sphinx.locale.l_()``
+     - 1.8
+     - 3.0
+     - :func:`sphinx.locale._()`
+
+   * - ``sphinx.locale.lazy_gettext()``
+     - 1.8
+     - 3.0
+     - :func:`sphinx.locale._()`
+
+   * - ``sphinx.locale.mygettext()``
+     - 1.8
+     - 3.0
+     - :func:`sphinx.locale._()`
+
+   * - ``sphinx.util.copy_static_entry()``
+     - 1.5
+     - 3.0
+     - ``sphinx.util.fileutil.copy_asset()``
+
+   * - ``sphinx.build_main()``
+     - 1.7
+     - 2.0
+     - ``sphinx.cmd.build.build_main()``
+
+   * - ``sphinx.ext.intersphinx.debug()``
+     - 1.7
+     - 2.0
+     - ``sphinx.ext.intersphinx.inspect_main()``
+
+   * - ``sphinx.ext.autodoc.format_annotation()``
+     - 1.7
+     - 2.0
+     - ``sphinx.util.inspect.Signature``
+
+   * - ``sphinx.ext.autodoc.formatargspec()``
+     - 1.7
+     - 2.0
+     - ``sphinx.util.inspect.Signature``
+
+   * - ``sphinx.ext.autodoc.AutodocReporter``
+     - 1.7
+     - 2.0
+     - ``sphinx.util.docutils.switch_source_input()``
+
+   * - ``sphinx.ext.autodoc.add_documenter()``
+     - 1.7
+     - 2.0
+     - :meth:`~sphinx.application.Sphinx.add_autodocumenter()`
+
+   * - ``sphinx.ext.autodoc.AutoDirective._register``
+     - 1.7
+     - 2.0
+     - :meth:`~sphinx.application.Sphinx.add_autodocumenter()`
+
+   * - ``AutoDirective._special_attrgetters``
+     - 1.7
+     - 2.0
+     - :meth:`~sphinx.application.Sphinx.add_autodoc_attrgetter()`
+
+   * - ``Sphinx.warn()``, ``Sphinx.info()``
+     - 1.6
+     - 2.0
+     - :ref:`logging-api`
+
+   * - ``BuildEnvironment.set_warnfunc()``
+     - 1.6
+     - 2.0
+     - :ref:`logging-api`
+
+   * - ``BuildEnvironment.note_toctree()``
+     - 1.6
+     - 2.0
+     - ``Toctree.note()`` (in ``sphinx.environment.adapters.toctree``)
+
+   * - ``BuildEnvironment.get_toc_for()``
+     - 1.6
+     - 2.0
+     - ``Toctree.get_toc_for()`` (in ``sphinx.environment.adapters.toctree``)
+
+   * - ``BuildEnvironment.get_toctree_for()``
+     - 1.6
+     - 2.0
+     - ``Toctree.get_toctree_for()`` (in ``sphinx.environment.adapters.toctree``)
+
+   * - ``BuildEnvironment.create_index()``
+     - 1.6
+     - 2.0
+     - ``IndexEntries.create_index()`` (in ``sphinx.environment.adapters.indexentries``)
+
+   * - ``sphinx.websupport``
+     - 1.6
+     - 2.0
+     - `sphinxcontrib-websupport`_
+
+       .. _sphinxcontrib-websupport: https://pypi.org/project/sphinxcontrib-websupport/
+
+   * - ``StandaloneHTMLBuilder.css_files``
+     - 1.6
+     - 2.0
+     - :meth:`~sphinx.application.Sphinx.add_stylesheet()`
+
+   * - ``document.settings.gettext_compact``
+     - 1.8
+     - 1.8
+     - :confval:`gettext_compact`
+
+   * - ``Sphinx.status_iterator()``
+     - 1.6
+     - 1.7
+     - ``sphinx.util.status_iterator()``
+
+   * - ``Sphinx.old_status_iterator()``
+     - 1.6
+     - 1.7
+     - ``sphinx.util.old_status_iterator()``
+
+   * - ``Sphinx._directive_helper()``
+     - 1.6
+     - 1.7
+     - ``sphinx.util.docutils.directive_helper()``
+
+   * - ``sphinx.util.compat.Directive``
+     - 1.6
+     - 1.7
+     - ``docutils.parsers.rst.Directive``
+
+   * - ``sphinx.util.compat.docutils_version``
+     - 1.6
+     - 1.7
+     - ``sphinx.util.docutils.__version_info__``
+
+.. note:: On deprecating on public APIs (internal functions and classes),
+          we also follow the policy as much as possible.
diff --git a/doc/extdev/domainapi.rst b/doc/extdev/domainapi.rst
new file mode 100644
index 0000000..d70b5db
--- /dev/null
+++ b/doc/extdev/domainapi.rst
@@ -0,0 +1,32 @@
+.. _domain-api:
+
+Domain API
+==========
+
+.. module:: sphinx.domains
+
+.. autoclass:: Domain
+   :members:
+
+.. autoclass:: ObjType
+
+.. autoclass:: Index
+   :members:
+
+.. module:: sphinx.directives
+
+.. autoclass:: ObjectDescription
+   :members:
+   :private-members: _toc_entry_name, _object_hierarchy_parts
+
+Python Domain
+-------------
+
+.. module:: sphinx.domains.python
+
+.. autoclass:: PythonDomain
+
+   .. autoattribute:: objects
+   .. autoattribute:: modules
+   .. automethod:: note_object
+   .. automethod:: note_module
diff --git a/doc/extdev/envapi.rst b/doc/extdev/envapi.rst
new file mode 100644
index 0000000..d7ec239
--- /dev/null
+++ b/doc/extdev/envapi.rst
@@ -0,0 +1,58 @@
+Build environment API
+=====================
+
+.. module:: sphinx.environment
+
+.. class:: BuildEnvironment
+
+   **Attributes**
+
+   .. attribute:: app
+
+      Reference to the :class:`.Sphinx` (application) object.
+
+   .. attribute:: config
+
+      Reference to the :class:`.Config` object.
+
+   .. attribute:: project
+
+      Target project.  See :class:`.Project`.
+
+   .. attribute:: srcdir
+
+      Source directory.
+
+   .. attribute:: doctreedir
+
+      Directory for storing pickled doctrees.
+
+   .. attribute:: events
+
+      An :class:`.EventManager` object.
+
+   .. attribute:: found_docs
+
+      A set of all existing docnames.
+
+   .. attribute:: metadata
+
+      Dictionary mapping docnames to "metadata" (see :ref:`metadata`).
+
+   .. attribute:: titles
+
+      Dictionary mapping docnames to the docutils node for their main title.
+
+   .. autoattribute:: docname
+
+   **Utility methods**
+
+   .. automethod:: doc2path
+
+   .. automethod:: relfn2path
+
+   .. automethod:: note_dependency
+
+   .. automethod:: new_serialno
+
+   .. automethod:: note_reread
diff --git a/doc/extdev/i18n.rst b/doc/extdev/i18n.rst
new file mode 100644
index 0000000..6b32b8b
--- /dev/null
+++ b/doc/extdev/i18n.rst
@@ -0,0 +1,97 @@
+.. _i18n-api:
+
+i18n API
+========
+
+.. currentmodule:: sphinx.locale
+
+.. autofunction:: init
+
+.. autofunction:: init_console
+
+.. autofunction:: get_translation
+
+.. autofunction:: _
+
+.. autofunction:: __
+
+
+.. _ext-i18n:
+
+Extension internationalization (`i18n`) and localization (`l10n`) using i18n API
+--------------------------------------------------------------------------------
+
+.. versionadded:: 1.8
+
+An extension may naturally come with message translations.  This is briefly
+summarized in :func:`sphinx.locale.get_translation` help.
+
+In practice, you have to:
+
+#. Choose a name for your message catalog, which must be unique.  Usually
+   the name of your extension is used for the name of message catalog.
+
+#. Mark in your extension sources all messages as translatable, via
+   :func:`sphinx.locale.get_translation` function, usually renamed ``_()``,
+   e.g.:
+
+   .. code-block:: python
+      :caption: src/__init__.py
+
+      from sphinx.locale import get_translation
+
+      MESSAGE_CATALOG_NAME = 'myextension'
+      _ = get_translation(MESSAGE_CATALOG_NAME)
+
+      translated_text = _('Hello Sphinx!')
+
+#. Set up your extension to be aware of its dedicated translations:
+
+   .. code-block:: python
+      :caption: src/__init__.py
+
+      def setup(app):
+          package_dir = path.abspath(path.dirname(__file__))
+          locale_dir = os.path.join(package_dir, 'locales')
+          app.add_message_catalog(MESSAGE_CATALOG_NAME, locale_dir)
+
+#. Generate message catalog template ``*.pot`` file, usually in ``locale/``
+   source directory, for example via `Babel`_:
+
+   .. code-block:: console
+
+      $ pybabel extract --output=src/locale/myextension.pot src/
+
+#. Create message catalogs (``*.po``) for each language which your extension
+   will provide localization, for example via `Babel`_:
+
+   .. code-block:: console
+
+      $ pybabel init --input-file=src/locale/myextension.pot --domain=myextension --output-dir=src/locale --locale=fr_FR
+
+#. Translate message catalogs for each language manually
+
+#. Compile message catalogs into ``*.mo`` files, for example via `Babel`_:
+
+   .. code-block:: console
+
+      $ pybabel compile --directory=src/locale --domain=myextension
+
+#. Ensure that message catalog files are distributed when your package will
+   be installed, by adding equivalent line in your extension ``MANIFEST.in``:
+
+   .. code-block:: ini
+      :caption: MANIFEST.in
+
+      recursive-include src *.pot *.po *.mo
+
+
+When the messages on your extension has been changed, you need to also update
+message catalog template and message catalogs, for example via `Babel`_:
+
+.. code-block:: console
+
+   $ pybabel extract --output=src/locale/myextension.pot src/
+   $ pybabel update --input-file=src/locale/myextension.pot --domain=myextension --output-dir=src/locale
+
+.. _Babel: https://babel.pocoo.org/
diff --git a/doc/extdev/index.rst b/doc/extdev/index.rst
new file mode 100644
index 0000000..014a806
--- /dev/null
+++ b/doc/extdev/index.rst
@@ -0,0 +1,218 @@
+.. _dev-extensions:
+
+Developing extensions for Sphinx
+================================
+
+Since many projects will need special features in their documentation, Sphinx
+is designed to be extensible on several levels.
+
+Here are a few things you can do in an extension:
+
+* Add new :term:`builder`\s to support new output formats or actions on the
+  parsed documents.
+* Register custom reStructuredText roles and directives, extending the markup
+  using the :doc:`markupapi`.
+* Add custom code to so-called "hook points" at strategic places throughout the
+  build process, allowing you to register a hook and run specialized code.
+  For example, see the :ref:`events`.
+
+An extension is simply a Python module with a ``setup()`` function. A user
+activates the extension by placing the extension's module name
+(or a sub-module) in their :confval:`extensions` configuration value.
+
+When :program:`sphinx-build` is executed, Sphinx will attempt to import each
+module that is listed, and execute ``yourmodule.setup(app)``. This
+function is used to prepare the extension (e.g., by executing Python code),
+linking resources that Sphinx uses in the build process (like CSS or HTML
+files), and notifying Sphinx of everything the extension offers (such
+as directive or role definitions). The ``app`` argument is an instance of
+:class:`.Sphinx` and gives you control over most aspects of the Sphinx build.
+
+.. note::
+
+    The configuration file itself can be treated as an extension if it
+    contains a ``setup()`` function.  All other extensions to load must be
+    listed in the :confval:`extensions` configuration value.
+
+The rest of this page describes some high-level aspects of developing
+extensions and various parts of Sphinx's behavior that you can control.
+For some examples of how extensions can be built and used to control different
+parts of Sphinx, see the :ref:`extension-tutorials-index`.
+
+.. _important-objects:
+
+Important objects
+-----------------
+
+There are several key objects whose API you will use while writing an
+extension. These are:
+
+**Application**
+   The application object (usually called ``app``) is an instance of
+   :class:`.Sphinx`.  It controls most high-level functionality, such as the
+   setup of extensions, event dispatching and producing output (logging).
+
+   If you have the environment object, the application is available as
+   ``env.app``.
+
+**Environment**
+   The build environment object (usually called ``env``) is an instance of
+   :class:`.BuildEnvironment`.  It is responsible for parsing the source
+   documents, stores all metadata about the document collection and is
+   serialized to disk after each build.
+
+   Its API provides methods to do with access to metadata, resolving references,
+   etc.  It can also be used by extensions to cache information that should
+   persist for incremental rebuilds.
+
+   If you have the application or builder object, the environment is available
+   as ``app.env`` or ``builder.env``.
+
+**Builder**
+   The builder object (usually called ``builder``) is an instance of a specific
+   subclass of :class:`.Builder`.  Each builder class knows how to convert the
+   parsed documents into an output format, or otherwise process them (e.g. check
+   external links).
+
+   If you have the application object, the builder is available as
+   ``app.builder``.
+
+**Config**
+   The config object (usually called ``config``) provides the values of
+   configuration values set in :file:`conf.py` as attributes.  It is an instance
+   of :class:`.Config`.
+
+   The config is available as ``app.config`` or ``env.config``.
+
+To see an example of use of these objects, refer to
+:doc:`../development/tutorials/index`.
+
+.. _build-phases:
+
+Build Phases
+------------
+
+One thing that is vital in order to understand extension mechanisms is the way
+in which a Sphinx project is built: this works in several phases.
+
+**Phase 0: Initialization**
+
+In this phase, almost nothing of interest to us happens.  The source
+directory is searched for source files, and extensions are initialized.
+Should a stored build environment exist, it is loaded, otherwise a new one is
+created.
+
+**Phase 1: Reading**
+
+In Phase 1, all source files (and on subsequent builds, those that are new or
+changed) are read and parsed.  This is the phase where directives and roles
+are encountered by docutils, and the corresponding code is executed.  The
+output of this phase is a *doctree* for each source file; that is a tree of
+docutils nodes.  For document elements that aren't fully known until all
+existing files are read, temporary nodes are created.
+
+There are nodes provided by docutils, which are documented `in the docutils
+documentation <https://docutils.sourceforge.io/docs/ref/doctree.html>`__.
+Additional nodes are provided by Sphinx and :ref:`documented here <nodes>`.
+
+During reading, the build environment is updated with all meta- and cross
+reference data of the read documents, such as labels, the names of headings,
+described Python objects and index entries.  This will later be used to
+replace the temporary nodes.
+
+The parsed doctrees are stored on the disk, because it is not possible to
+hold all of them in memory.
+
+**Phase 2: Consistency checks**
+
+Some checking is done to ensure no surprises in the built documents.
+
+**Phase 3: Resolving**
+
+Now that the metadata and cross-reference data of all existing documents is
+known, all temporary nodes are replaced by nodes that can be converted into
+output using components called transforms.  For example, links are created
+for object references that exist, and simple literal nodes are created for
+those that don't.
+
+**Phase 4: Writing**
+
+This phase converts the resolved doctrees to the desired output format, such
+as HTML or LaTeX.  This happens via a so-called docutils writer that visits
+the individual nodes of each doctree and produces some output in the process.
+
+.. note::
+
+   Some builders deviate from this general build plan, for example, the builder
+   that checks external links does not need anything more than the parsed
+   doctrees and therefore does not have phases 2--4.
+
+To see an example of application, refer to :doc:`../development/tutorials/todo`.
+
+.. _ext-metadata:
+
+Extension metadata
+------------------
+
+.. versionadded:: 1.3
+
+The ``setup()`` function can return a dictionary.  This is treated by Sphinx
+as metadata of the extension.  Metadata keys currently recognized are:
+
+* ``'version'``: a string that identifies the extension version.  It is used for
+  extension version requirement checking (see :confval:`needs_extensions`) and
+  informational purposes.  If not given, ``"unknown version"`` is substituted.
+* ``'env_version'``: an integer that identifies the version of env data
+  structure if the extension stores any data to environment.  It is used to
+  detect the data structure has been changed from last build.  The extensions
+  have to increment the version when data structure has changed.  If not given,
+  Sphinx considers the extension does not stores any data to environment.
+* ``'parallel_read_safe'``: a boolean that specifies if parallel reading of
+  source files can be used when the extension is loaded.  It defaults to
+  ``False``, i.e. you have to explicitly specify your extension to be
+  parallel-read-safe after checking that it is.
+
+  .. note:: The *parallel-read-safe* extension must satisfy the following
+            conditions:
+
+            * The core logic of the extension is parallelly executable during
+              the reading phase.
+            * It has event handlers for :event:`env-merge-info` and
+              :event:`env-purge-doc` events if it stores data to the build
+              environment object (env) during the reading phase.
+
+* ``'parallel_write_safe'``: a boolean that specifies if parallel writing of
+  output files can be used when the extension is loaded.  Since extensions
+  usually don't negatively influence the process, this defaults to ``True``.
+
+  .. note:: The *parallel-write-safe* extension must satisfy the following
+            conditions:
+
+            * The core logic of the extension is parallelly executable during
+              the writing phase.
+
+
+APIs used for writing extensions
+--------------------------------
+
+These sections provide a more complete description of the tools at your
+disposal when developing Sphinx extensions. Some are core to Sphinx
+(such as the :doc:`appapi`) while others trigger specific behavior
+(such as the :doc:`i18n`)
+
+.. toctree::
+   :maxdepth: 2
+
+   appapi
+   projectapi
+   envapi
+   builderapi
+   collectorapi
+   markupapi
+   domainapi
+   parserapi
+   nodes
+   logging
+   i18n
+   utils
+   deprecated
diff --git a/doc/extdev/logging.rst b/doc/extdev/logging.rst
new file mode 100644
index 0000000..e6c4dc6
--- /dev/null
+++ b/doc/extdev/logging.rst
@@ -0,0 +1,66 @@
+.. _logging-api:
+
+Logging API
+===========
+
+.. currentmodule:: sphinx.util.logging
+
+.. autofunction:: getLogger(name)
+
+.. autoclass:: SphinxLoggerAdapter(logging.LoggerAdapter)
+
+   .. method:: SphinxLoggerAdapter.error(msg, *args, **kwargs)
+   .. method:: SphinxLoggerAdapter.critical(msg, *args, **kwargs)
+   .. method:: SphinxLoggerAdapter.warning(msg, *args, **kwargs)
+
+      Logs a message on this logger with the specified level.
+      Basically, the arguments are as with python's logging module.
+
+      In addition, Sphinx logger supports following keyword arguments:
+
+      **type**, ***subtype***
+        Categories of warning logs.  It is used to suppress
+        warnings by :confval:`suppress_warnings` setting.
+
+      **location**
+        Where the warning happened.  It is used to include
+        the path and line number in each log.  It allows docname,
+        tuple of docname and line number and nodes::
+
+          logger = sphinx.util.logging.getLogger(__name__)
+          logger.warning('Warning happened!', location='index')
+          logger.warning('Warning happened!', location=('chapter1/index', 10))
+          logger.warning('Warning happened!', location=some_node)
+
+      **color**
+        The color of logs.  By default, error level logs are colored as
+        ``"darkred"``, critical level ones is not colored, and warning level
+        ones are colored as ``"red"``.
+
+   .. method:: SphinxLoggerAdapter.log(level, msg, *args, **kwargs)
+   .. method:: SphinxLoggerAdapter.info(msg, *args, **kwargs)
+   .. method:: SphinxLoggerAdapter.verbose(msg, *args, **kwargs)
+   .. method:: SphinxLoggerAdapter.debug(msg, *args, **kwargs)
+
+      Logs a message to this logger with the specified level.
+      Basically, the arguments are as with python's logging module.
+
+      In addition, Sphinx logger supports following keyword arguments:
+
+      **nonl**
+        If true, the logger does not fold lines at the end of the log message.
+        The default is ``False``.
+
+      **location**
+        Where the message emitted.  For more detail, see
+        :meth:`SphinxLoggerAdapter.warning`.
+
+      **color**
+        The color of logs.  By default, info and verbose level logs are not
+        colored, and debug level ones are colored as ``"darkgray"``.
+
+.. autofunction:: pending_logging()
+
+.. autofunction:: pending_warnings()
+
+.. autofunction:: prefixed_warnings()
diff --git a/doc/extdev/markupapi.rst b/doc/extdev/markupapi.rst
new file mode 100644
index 0000000..8fc884d
--- /dev/null
+++ b/doc/extdev/markupapi.rst
@@ -0,0 +1,152 @@
+Docutils markup API
+===================
+
+This section describes the API for adding ReST markup elements (roles and
+directives).
+
+Roles
+-----
+
+
+Directives
+----------
+
+Directives are handled by classes derived from
+``docutils.parsers.rst.Directive``.  They have to be registered by an extension
+using :meth:`.Sphinx.add_directive` or :meth:`.Sphinx.add_directive_to_domain`.
+
+.. module:: docutils.parsers.rst
+
+.. class:: Directive
+
+   The markup syntax of the new directive is determined by the follow five class
+   attributes:
+
+   .. autoattribute:: required_arguments
+   .. autoattribute:: optional_arguments
+   .. autoattribute:: final_argument_whitespace
+   .. autoattribute:: option_spec
+
+      Option validator functions take a single parameter, the option argument
+      (or ``None`` if not given), and should validate it or convert it to the
+      proper form.  They raise :exc:`ValueError` or :exc:`TypeError` to indicate
+      failure.
+
+      There are several predefined and possibly useful validators in the
+      :mod:`docutils.parsers.rst.directives` module.
+
+   .. autoattribute:: has_content
+
+   New directives must implement the :meth:`run` method:
+
+   .. method:: run()
+
+      This method must process the directive arguments, options and content, and
+      return a list of Docutils/Sphinx nodes that will be inserted into the
+      document tree at the point where the directive was encountered.
+
+   Instance attributes that are always set on the directive are:
+
+   .. attribute:: name
+
+      The directive name (useful when registering the same directive class under
+      multiple names).
+
+   .. attribute:: arguments
+
+      The arguments given to the directive, as a list.
+
+   .. attribute:: options
+
+      The options given to the directive, as a dictionary mapping option names
+      to validated/converted values.
+
+   .. attribute:: content
+
+      The directive content, if given, as a :class:`.ViewList`.
+
+   .. attribute:: lineno
+
+      The absolute line number on which the directive appeared.  This is not
+      always a useful value; use :attr:`srcline` instead.
+
+   .. attribute:: content_offset
+
+      Internal offset of the directive content.  Used when calling
+      ``nested_parse`` (see below).
+
+   .. attribute:: block_text
+
+      The string containing the entire directive.
+
+   .. attribute:: state
+                  state_machine
+
+      The state and state machine which controls the parsing.  Used for
+      ``nested_parse``.
+
+
+ViewLists
+^^^^^^^^^
+
+Docutils represents document source lines in a class
+``docutils.statemachine.ViewList``.  This is a list with extended functionality
+-- for one, slicing creates views of the original list, and also the list
+contains information about the source line numbers.
+
+The :attr:`Directive.content` attribute is a ViewList.  If you generate content
+to be parsed as ReST, you have to create a ViewList yourself.  Important for
+content generation are the following points:
+
+* The constructor takes a list of strings (lines) and a source (document) name.
+
+* The ``.append()`` method takes a line and a source name as well.
+
+
+Parsing directive content as ReST
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Many directives will contain more markup that must be parsed.  To do this, use
+one of the following APIs from the :meth:`Directive.run` method:
+
+* ``self.state.nested_parse``
+* :func:`sphinx.util.nodes.nested_parse_with_titles` -- this allows titles in
+  the parsed content.
+
+Both APIs parse the content into a given node. They are used like this::
+
+   node = docutils.nodes.paragraph()
+   # either
+   nested_parse_with_titles(self.state, self.result, node)
+   # or
+   self.state.nested_parse(self.result, 0, node)
+
+.. note::
+
+   ``sphinx.util.docutils.switch_source_input()`` allows to change a target file
+   during nested_parse.  It is useful to mixed contents.  For example, ``sphinx.
+   ext.autodoc`` uses it to parse docstrings::
+
+       from sphinx.util.docutils import switch_source_input
+
+       # Switch source_input between parsing content.
+       # Inside this context, all parsing errors and warnings are reported as
+       # happened in new source_input (in this case, ``self.result``).
+       with switch_source_input(self.state, self.result):
+           node = docutils.nodes.paragraph()
+           self.state.nested_parse(self.result, 0, node)
+
+   .. deprecated:: 1.7
+
+      Until Sphinx-1.6, ``sphinx.ext.autodoc.AutodocReporter`` is used for this
+      purpose.  For now, it is replaced by ``switch_source_input()``.
+
+If you don't need the wrapping node, you can use any concrete node type and
+return ``node.children`` from the Directive.
+
+
+.. seealso::
+
+   `Creating directives`_ HOWTO of the Docutils documentation
+
+.. _Creating directives: https://docutils.sourceforge.io/docs/howto/rst-directives.html
diff --git a/doc/extdev/nodes.rst b/doc/extdev/nodes.rst
new file mode 100644
index 0000000..77872df
--- /dev/null
+++ b/doc/extdev/nodes.rst
@@ -0,0 +1,71 @@
+.. _nodes:
+
+Doctree node classes added by Sphinx
+====================================
+
+.. module:: sphinx.addnodes
+
+Nodes for domain-specific object descriptions
+---------------------------------------------
+
+Top-level nodes
+...............
+
+These nodes form the top-most levels of object descriptions.
+
+.. autoclass:: desc
+.. autoclass:: desc_signature
+.. autoclass:: desc_signature_line
+.. autoclass:: desc_content
+.. autoclass:: desc_inline
+
+Nodes for high-level structure in signatures
+............................................
+
+These nodes occur in in non-multiline :py:class:`desc_signature` nodes
+and in :py:class:`desc_signature_line` nodes.
+
+.. autoclass:: desc_name
+.. autoclass:: desc_addname
+
+.. autoclass:: desc_type
+.. autoclass:: desc_returns
+.. autoclass:: desc_parameterlist
+.. autoclass:: desc_parameter
+.. autoclass:: desc_optional
+.. autoclass:: desc_annotation
+
+New admonition-like constructs
+------------------------------
+
+.. autoclass:: versionmodified
+.. autoclass:: seealso
+
+Other paragraph-level nodes
+-------------------------------
+
+.. autoclass:: compact_paragraph
+
+New inline nodes
+----------------
+
+.. autoclass:: index
+.. autoclass:: pending_xref
+.. autoclass:: pending_xref_condition
+.. autoclass:: literal_emphasis
+.. autoclass:: download_reference
+
+Special nodes
+-------------
+
+.. autoclass:: only
+.. autoclass:: meta
+.. autoclass:: highlightlang
+
+You should not need to generate the nodes below in extensions.
+
+.. autoclass:: glossary
+.. autoclass:: toctree
+.. autoclass:: start_of_file
+.. autoclass:: productionlist
+.. autoclass:: production
diff --git a/doc/extdev/parserapi.rst b/doc/extdev/parserapi.rst
new file mode 100644
index 0000000..c5db2ac
--- /dev/null
+++ b/doc/extdev/parserapi.rst
@@ -0,0 +1,38 @@
+.. _parser-api:
+
+Parser API
+==========
+
+`The docutils documentation describes`__ parsers as follows:
+
+    The Parser analyzes the input document and creates a node tree
+    representation.
+
+__ https://docutils.sourceforge.io/docs/dev/hacking.html#parsing-the-document
+
+In Sphinx, the parser modules works as same as docutils.  The parsers are
+registered to Sphinx by extensions using Application APIs;
+:meth:`.Sphinx.add_source_suffix()` and :meth:`.Sphinx.add_source_parser()`.
+
+The *source suffix* is a mapping from file suffix to file type.  For example,
+``.rst`` file is mapped to ``'restructuredtext'`` type.  Sphinx uses the
+file type to looking for parsers from registered list.  On searching,
+Sphinx refers to the ``Parser.supported`` attribute and picks up a parser
+which contains the file type in the attribute.
+
+The users can override the source suffix mappings using
+:confval:`source_suffix` like following::
+
+    # a mapping from file suffix to file types
+    source_suffix = {
+        '.rst': 'restructuredtext',
+        '.md': 'markdown',
+    }
+
+You should indicate file types your parser supports. This will allow users
+to configure their settings appropriately.
+
+.. module:: sphinx.parsers
+
+.. autoclass:: Parser
+   :members:
diff --git a/doc/extdev/projectapi.rst b/doc/extdev/projectapi.rst
new file mode 100644
index 0000000..238aeb4
--- /dev/null
+++ b/doc/extdev/projectapi.rst
@@ -0,0 +1,9 @@
+.. _project-api:
+
+Project API
+===========
+
+.. currentmodule:: sphinx.project
+
+.. autoclass:: Project
+   :members:
diff --git a/doc/extdev/utils.rst b/doc/extdev/utils.rst
new file mode 100644
index 0000000..e842f30
--- /dev/null
+++ b/doc/extdev/utils.rst
@@ -0,0 +1,37 @@
+Utilities
+=========
+
+Sphinx provides utility classes and functions to develop extensions.
+
+Base classes for components
+---------------------------
+
+These base classes are useful to allow your extensions to obtain Sphinx
+components (e.g. :class:`.Config`, :class:`.BuildEnvironment` and so on) easily.
+
+.. note:: The subclasses of them might not work with bare docutils because they
+          are strongly coupled with Sphinx.
+
+.. autoclass:: sphinx.transforms.SphinxTransform
+   :members:
+
+.. autoclass:: sphinx.transforms.post_transforms.SphinxPostTransform
+   :members:
+
+.. autoclass:: sphinx.util.docutils.SphinxDirective
+   :members:
+
+.. autoclass:: sphinx.util.docutils.SphinxRole
+   :members:
+
+.. autoclass:: sphinx.util.docutils.ReferenceRole
+   :members:
+
+.. autoclass:: sphinx.transforms.post_transforms.images.ImageConverter
+   :members:
+
+Utility components
+------------------
+
+.. autoclass:: sphinx.events.EventManager
+   :members: