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.
danking · Mar 1, 2018 · bd898be · bd898be
1 parent 6bce067
commit bd898be
Show file tree

Hide file tree

Showing 2 changed files with 131 additions and 4 deletions.
diff --git 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
@@ -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.