Deprecate imports for compatibility

CHANGES

@@ -14,6 +14,23 @@ Deprecated
 ----------
 
 * ``sphinx.builders.latex.LaTeXBuilder.apply_transforms()``
+* ``sphinx.directives.Acks``
+* ``sphinx.directives.Author``
+* ``sphinx.directives.Centered``
+* ``sphinx.directives.Class``
+* ``sphinx.directives.CodeBlock``
+* ``sphinx.directives.Figure``
+* ``sphinx.directives.HList``
+* ``sphinx.directives.Highlight``
+* ``sphinx.directives.Include``
+* ``sphinx.directives.Index``
+* ``sphinx.directives.LiteralInclude``
+* ``sphinx.directives.Meta``
+* ``sphinx.directives.Only``
+* ``sphinx.directives.SeeAlso``
+* ``sphinx.directives.TabularColumns``
+* ``sphinx.directives.TocTree``
+* ``sphinx.directives.VersionChange``
 * ``sphinx.environment.NoUri``
 * ``sphinx.ext.autodoc.importer.MockFinder``
 * ``sphinx.ext.autodoc.importer.MockLoader``

doc/extdev/deprecated.rst

@@ -31,6 +31,91 @@ The following is a list of deprecated interfaces.
      - 4.0
      - N/A
 
+   * - ``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.environment.NoUri``
      - 2.1
      - 4.0

sphinx/directives/__init__.py

@@ -15,6 +15,7 @@ from docutils import nodes
 from docutils.parsers.rst import directives, roles
 
 from sphinx import addnodes
+from sphinx.deprecation import RemovedInSphinx40Warning, deprecated_alias
 from sphinx.util import docutils
 from sphinx.util.docfields import DocFieldTransformer
 from sphinx.util.docutils import SphinxDirective
@@ -186,10 +187,6 @@ class ObjectDescription(SphinxDirective):
         return [self.indexnode, node]
 
 
-# backwards compatible old name
-DescDirective = ObjectDescription
-
-
 class DefaultRole(SphinxDirective):
     """
     Set the default interpreted text role.  Overridden from docutils.
@@ -242,7 +239,6 @@ class DefaultDomain(SphinxDirective):
         self.env.temp_data['default_domain'] = self.env.domains.get(domain_name)
         return []
 
-# import all directives sphinx provides (for compatibility)
 from sphinx.directives.code import (  # noqa
     Highlight, CodeBlock, LiteralInclude
 )
@@ -254,6 +250,32 @@ from sphinx.directives.patches import (  # noqa
     Figure, Meta
 )
 
+deprecated_alias('sphinx.directives',
+                 {
+                     'Highlight': Highlight,
+                     'CodeBlock': CodeBlock,
+                     'LiteralInclude': LiteralInclude,
+                     'TocTree': TocTree,
+                     'Author': Author,
+                     'Index': Index,
+                     'VersionChange': VersionChange,
+                     'SeeAlso': SeeAlso,
+                     'TabularColumns': TabularColumns,
+                     'Centered': Centered,
+                     'Acks': Acks,
+                     'HList': HList,
+                     'Only': Only,
+                     'Include': Include,
+                     'Class': Class,
+                     'Figure': Figure,
+                     'Meta': Meta,
+                 },
+                 RemovedInSphinx40Warning)
+
+
+# backwards compatible old name (will be marked deprecated in 3.0)
+DescDirective = ObjectDescription
+
 
 def setup(app):
     # type: (Sphinx) -> Dict[str, Any]