Close #9595: Deprecate setuptools integration

CHANGES

@@ -22,6 +22,9 @@ Incompatible changes
 Deprecated
 ----------
 
+* setuptools integration.  The ``build_sphinx`` sub-command for setup.py is
+  marked as deprecated to follow the policy of setuptools team.
+
 Features added
 --------------
 

doc/extdev/deprecated.rst

@@ -22,6 +22,11 @@ The following is a list of deprecated interfaces.
      - (will be) Removed
      - Alternatives
 
+   * - :doc:`Setuptools integration </usage/advanced/setuptools>`
+     - 5.0
+     - 7.0
+     - N/A
+
    * - ``sphinx.writers.latex.LaTeXWriter.docclasses``
      - 5.0
      - 7.0

doc/usage/advanced/setuptools.rst

@@ -6,6 +6,10 @@ Setuptools integration
 Sphinx supports integration with setuptools and distutils through a custom
 command - :class:`~sphinx.setup_command.BuildDoc`.
 
+.. deprecated:: 5.0
+
+   This feature will be removed in v7.0.
+
 Using setuptools integration
 ----------------------------
 

sphinx/setup_command.py

@@ -13,6 +13,7 @@
 
 import os
 import sys
+import warnings
 from distutils.cmd import Command
 from distutils.errors import DistutilsExecError
 from io import StringIO
@@ -20,6 +21,7 @@ from typing import Any, Dict
 
 from sphinx.application import Sphinx
 from sphinx.cmd.build import handle_exception
+from sphinx.deprecation import RemovedInSphinx70Warning
 from sphinx.util.console import color_terminal, nocolor
 from sphinx.util.docutils import docutils_namespace, patch_docutils
 from sphinx.util.osutil import abspath
@@ -140,6 +142,9 @@ class BuildDoc(Command):
             for builder in self.builder]
 
     def run(self) -> None:
+        warnings.warn('setup.py build_sphinx is deprecated.',
+                      RemovedInSphinx70Warning, stacklevel=2)
+
         if not color_terminal():
             nocolor()
         if not self.verbose:  # type: ignore