From bd898be3fce2eed685b958490c18055ac351138d Mon Sep 17 00:00:00 2001
From: Takeshi KOMIYA <i.tkomiya@gmail.com>
Date: Fri, 23 Feb 2018 21:33:16 +0900
Subject: [PATCH] doc: Add deprecation list

So far, deprecated APIs are only listed as CHANGES entry.  But
they are not listed in one place.  In this change, I gathered them
to docs as a list.
As a side effect, it makes CHANGES entry simple.
---
 CHANGES              |   9 ++--
 doc/extdev/index.rst | 126 +++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 131 insertions(+), 4 deletions(-)

diff --git a/CHANGES b/CHANGES
index 5a508b2aa..f337471e3 100644
--- a/CHANGES
+++ b/CHANGES
@@ -27,12 +27,13 @@ Release 1.7.1 (released Feb 23, 2018)
 Deprecated
 ----------
 
-* #4623: ``sphinx.build_main()`` is deprecated. Use
-  ``sphinx.cmd.build.build_main()`` instead.
+* #4623: ``sphinx.build_main()`` is deprecated.
 * autosummary: The interface of ``sphinx.ext.autosummary.get_documenter()`` has
   been changed (Since 1.7.0)
-* #4664: ``sphinx.ext.intersphinx.debug()`` is deprecated. Use
-  ``sphinx.ext.intersphinx.inspect_main()`` instead.
+* #4664: ``sphinx.ext.intersphinx.debug()`` is deprecated.
+
+For more details, see `deprecation APIs list
+<http://www.sphinx-doc.org/en/master/extdev/index.html#deprecated-apis>`_
 
 Bugs fixed
 ----------
diff --git a/doc/extdev/index.rst b/doc/extdev/index.rst
index b6c71cca6..ace43fd71 100644
--- a/doc/extdev/index.rst
+++ b/doc/extdev/index.rst
@@ -86,3 +86,129 @@ APIs used for writing extensions
    parserapi
    nodes
    logging
+
+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 thme 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 interface.
+
+.. list-table:: deprecated APIs
+   :header-rows: 1
+
+   * - Target
+     - Deprecated
+     - (will be) Removed
+     - Alternatives
+
+   * - ``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 <https://pypi.python.org/pypi/sphinxcontrib-websupport>`_
+
+   * - ``StandaloneHTMLBuilder.css_files``
+     - 1.6
+     - 2.0
+     - :meth:`~sphinx.application.Sphinx.add_stylesheet()`
+
+   * - ``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.