Remove the deprecated Setuptools integration (#11363)

11 files changed, 3 insertions, 402 deletions

diff --git a/CHANGES b/CHANGES
index 0b82096c2..049019b33 100644
--- a/CHANGES
+++ b/CHANGES
@@ -11,6 +11,8 @@ Incompatible changes
   ``DefaultSplitter`` in ``sphinx.search.ja``.
 * #11360: Remove deprecated ``make_old_id`` functions in domain object
   description classes.
+* #11363: Remove the Setuptools integration (``build_sphinx`` hook in
+  ``setup.py``).
 
 Deprecated
 ----------
diff --git a/doc/conf.py b/doc/conf.py
index 19b8b2a2e..8bf8d90a7 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -231,9 +231,6 @@ def setup(app):
     app.add_object_type('confval', 'confval',
                         objname='configuration value',
                         indextemplate='pair: %s; configuration value')
-    app.add_object_type('setuptools-confval', 'setuptools-confval',
-                        objname='setuptools configuration value',
-                        indextemplate='pair: %s; setuptools configuration value')
     fdesc = GroupedField('parameter', label='Parameters',
                          names=['param'], can_collapse=True)
     app.add_object_type('event', 'event', 'pair: %s; event', parse_event,
diff --git a/doc/extdev/deprecated.rst b/doc/extdev/deprecated.rst
index 8029714df..863af3165 100644
--- a/doc/extdev/deprecated.rst
+++ b/doc/extdev/deprecated.rst
@@ -102,7 +102,7 @@ The following is a list of deprecated interfaces.
      - 7.0
      - The standard library ``json`` module.
 
-   * - :doc:`Setuptools integration </usage/advanced/setuptools>`
+   * - The Setuptools integration (``setup.py build_sphinx``)
      - 5.0
      - 7.0
      - N/A
diff --git a/doc/usage/advanced/setuptools.rst b/doc/usage/advanced/setuptools.rst
deleted file mode 100644
index 6fe68dcdd..000000000
--- a/doc/usage/advanced/setuptools.rst
+++ /dev/null
@@ -1,200 +0,0 @@
-.. _setuptools:
-
-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 Sphinx 7.0.
-
-Using setuptools integration
-----------------------------
-
-The Sphinx build can then be triggered from distutils, and some Sphinx
-options can be set in ``setup.py`` or ``setup.cfg`` instead of Sphinx's own
-configuration file.
-
-For instance, from ``setup.py``::
-
-    # this is only necessary when not using setuptools/distribute
-    from sphinx.setup_command import BuildDoc
-    cmdclass = {'build_sphinx': BuildDoc}
-
-    name = 'My project'
-    version = '1.2'
-    release = '1.2.0'
-    setup(
-        name=name,
-        author='Bernard Montgomery',
-        version=release,
-        cmdclass=cmdclass,
-        # these are optional and override conf.py settings
-        command_options={
-            'build_sphinx': {
-                'project': ('setup.py', name),
-                'version': ('setup.py', version),
-                'release': ('setup.py', release),
-                'source_dir': ('setup.py', 'doc')}},
-    )
-
-.. note::
-
-    If you set Sphinx options directly in the ``setup()`` command, replace
-    hyphens in variable names with underscores. In the example above,
-    ``source-dir`` becomes ``source_dir``.
-
-Or add this section in ``setup.cfg``::
-
-    [build_sphinx]
-    project = 'My project'
-    version = 1.2
-    release = 1.2.0
-    source-dir = 'doc'
-
-Once configured, call this by calling the relevant command on ``setup.py``::
-
-    $ python setup.py build_sphinx
-
-Options for setuptools integration
-----------------------------------
-
-.. setuptools-confval:: fresh-env
-
-   A boolean that determines whether the saved environment should be discarded
-   on build. Default is false.
-
-   This can also be set by passing the `-E` flag to ``setup.py``:
-
-   .. code-block:: console
-
-      $ python setup.py build_sphinx -E
-
-.. setuptools-confval:: all-files
-
-   A boolean that determines whether all files should be built from scratch.
-   Default is false.
-
-   This can also be set by passing the `-a` flag to ``setup.py``:
-
-   .. code-block:: console
-
-      $ python setup.py build_sphinx -a
-
-.. setuptools-confval:: source-dir
-
-   The target source directory. This can be relative to the ``setup.py`` or
-   ``setup.cfg`` file, or it can be absolute.  It defaults to ``./doc`` or
-   ``./docs`` if either contains a file named ``conf.py`` (checking ``./doc``
-   first); otherwise it defaults to the current directory.
-
-   This can also be set by passing the `-s` flag to ``setup.py``:
-
-   .. code-block:: console
-
-      $ python setup.py build_sphinx -s $SOURCE_DIR
-
-.. setuptools-confval:: build-dir
-
-   The target build directory. This can be relative to the ``setup.py`` or
-   ``setup.cfg`` file, or it can be absolute. Default is ``./build/sphinx``.
-
-.. setuptools-confval:: config-dir
-
-   Location of the configuration directory. This can be relative to the
-   ``setup.py`` or ``setup.cfg`` file, or it can be absolute. Default is to use
-   `source-dir`.
-
-   This can also be set by passing the `-c` flag to ``setup.py``:
-
-   .. code-block:: console
-
-      $ python setup.py build_sphinx -c $CONFIG_DIR
-
-   .. versionadded:: 1.0
-
-.. setuptools-confval:: builder
-
-   The builder or list of builders to use. Default is ``html``.
-
-   This can also be set by passing the `-b` flag to ``setup.py``:
-
-   .. code-block:: console
-
-      $ python setup.py build_sphinx -b $BUILDER
-
-   .. versionchanged:: 1.6
-      This can now be a comma- or space-separated list of builders
-
-.. setuptools-confval:: warning-is-error
-
-   A boolean that ensures Sphinx warnings will result in a failed build.
-   Default is false.
-
-   This can also be set by passing the `-W` flag to ``setup.py``:
-
-   .. code-block:: console
-
-      $ python setup.py build_sphinx -W
-
-   .. versionadded:: 1.5
-
-.. setuptools-confval:: project
-
-   The documented project's name. Default is ``''``.
-
-   .. versionadded:: 1.0
-
-.. setuptools-confval:: version
-
-   The short X.Y version. Default is ``''``.
-
-   .. versionadded:: 1.0
-
-.. setuptools-confval:: release
-
-   The full version, including alpha/beta/rc tags. Default is ``''``.
-
-   .. versionadded:: 1.0
-
-.. setuptools-confval:: today
-
-   How to format the current date, used as the replacement for ``|today|``.
-   Default is ``''``.
-
-   .. versionadded:: 1.0
-
-.. setuptools-confval:: link-index
-
-   A boolean that ensures index.html will be linked to the root doc. Default
-   is false.
-
-   This can also be set by passing the `-i` flag to ``setup.py``:
-
-   .. code-block:: console
-
-      $ python setup.py build_sphinx -i
-
-   .. versionadded:: 1.0
-
-.. setuptools-confval:: copyright
-
-   The copyright string. Default is ``''``.
-
-   .. versionadded:: 1.3
-
-.. setuptools-confval:: nitpicky
-
-   Run in nit-picky mode.  Currently, this generates warnings for all missing
-   references.  See the config value :confval:`nitpick_ignore` for a way to
-   exclude some references as "known missing".
-
-   .. versionadded:: 1.8
-
-.. setuptools-confval:: pdb
-
-   A boolean to configure ``pdb`` on exception. Default is false.
-
-   .. versionadded:: 1.5
diff --git a/doc/usage/index.rst b/doc/usage/index.rst
index 0f4c22211..fd8cdd8bf 100644
--- a/doc/usage/index.rst
+++ b/doc/usage/index.rst
@@ -17,5 +17,4 @@ looking for guidance on extending Sphinx, refer to :doc:`/development/index`.
    extensions/index
    theming
    advanced/intl
-   advanced/setuptools
    advanced/websupport/index
diff --git a/doc/usage/quickstart.rst b/doc/usage/quickstart.rst
index abfa269d8..0773f6030 100644
--- a/doc/usage/quickstart.rst
+++ b/doc/usage/quickstart.rst
@@ -332,7 +332,6 @@ More topics to be covered
 - :doc:`Other extensions </usage/extensions/index>`:
 - Static files
 - :doc:`Selecting a theme </usage/theming>`
-- :doc:`/usage/advanced/setuptools`
 - :ref:`Templating <templating>`
 - Using extensions
 - :ref:`Writing extensions <dev-extensions>`
diff --git a/pyproject.toml b/pyproject.toml
index 6c2d707c7..424af4938 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -36,7 +36,6 @@ classifiers = [
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: Implementation :: CPython",
     "Programming Language :: Python :: Implementation :: PyPy",
-    "Framework :: Setuptools Plugin",
     "Framework :: Sphinx",
     "Framework :: Sphinx :: Extension",
     "Framework :: Sphinx :: Theme",
diff --git a/sphinx/setup_command.py b/sphinx/setup_command.py
deleted file mode 100644
index cbcdb2ff2..000000000
--- a/sphinx/setup_command.py
+++ /dev/null
@@ -1,192 +0,0 @@
-"""Setuptools/distutils commands to assist the building of sphinx documentation.
-
-:author: Sebastian Wiesner <basti.wiesner@gmx.net>
-"""
-
-from __future__ import annotations
-
-import os
-import sys
-import warnings
-from io import StringIO
-from typing import Any
-
-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
-
-try:
-    from setuptools import Command
-    from setuptools.errors import ExecError
-except ImportError:
-    from distutils.cmd import Command
-    from distutils.errors import DistutilsExecError as ExecError
-
-
-class BuildDoc(Command):
-    """
-    Distutils command to build Sphinx documentation.
-
-    The Sphinx build can then be triggered from distutils, and some Sphinx
-    options can be set in ``setup.py`` or ``setup.cfg`` instead of Sphinx's
-    own configuration file.
-
-    For instance, from `setup.py`::
-
-       # this is only necessary when not using setuptools/distribute
-       from sphinx.setup_command import BuildDoc
-       cmdclass = {'build_sphinx': BuildDoc}
-
-       name = 'My project'
-       version = '1.2'
-       release = '1.2.0'
-       setup(
-           name=name,
-           author='Bernard Montgomery',
-           version=release,
-           cmdclass=cmdclass,
-           # these are optional and override conf.py settings
-           command_options={
-               'build_sphinx': {
-                   'project': ('setup.py', name),
-                   'version': ('setup.py', version),
-                   'release': ('setup.py', release)}},
-       )
-
-    Or add this section in ``setup.cfg``::
-
-       [build_sphinx]
-       project = 'My project'
-       version = 1.2
-       release = 1.2.0
-    """
-
-    description = 'Build Sphinx documentation'
-    user_options = [
-        ('fresh-env', 'E', 'discard saved environment'),
-        ('all-files', 'a', 'build all files'),
-        ('source-dir=', 's', 'Source directory'),
-        ('build-dir=', None, 'Build directory'),
-        ('config-dir=', 'c', 'Location of the configuration directory'),
-        ('builder=', 'b', 'The builder (or builders) to use. Can be a comma- '
-         'or space-separated list. Defaults to "html"'),
-        ('warning-is-error', 'W', 'Turn warning into errors'),
-        ('project=', None, "The documented project's name"),
-        ('version=', None, 'The short X.Y version'),
-        ('release=', None, 'The full version, including alpha/beta/rc tags'),
-        ('today=', None, 'How to format the current date, used as the '
-         'replacement for |today|'),
-        ('link-index', 'i', 'Link index.html to the master doc'),
-        ('copyright', None, 'The copyright string'),
-        ('pdb', None, 'Start pdb on exception'),
-        ('verbosity', 'v', 'increase verbosity (can be repeated)'),
-        ('nitpicky', 'n', 'nit-picky mode, warn about all missing references'),
-        ('keep-going', None, 'With -W, keep going when getting warnings'),
-    ]
-    boolean_options = ['fresh-env', 'all-files', 'warning-is-error',
-                       'link-index', 'nitpicky']
-
-    def initialize_options(self) -> None:
-        self.fresh_env = self.all_files = False
-        self.pdb = False
-        self.source_dir: str | None = None
-        self.build_dir: str | None = None
-        self.builder = 'html'
-        self.warning_is_error = False
-        self.project = ''
-        self.version = ''
-        self.release = ''
-        self.today = ''
-        self.config_dir: str | None = None
-        self.link_index = False
-        self.copyright = ''
-        # Link verbosity to distutils' (which uses 1 by default).
-        self.verbosity = self.distribution.verbose - 1
-        self.traceback = False
-        self.nitpicky = False
-        self.keep_going = False
-
-    def _guess_source_dir(self) -> str:
-        for guess in ('doc', 'docs'):
-            if not os.path.isdir(guess):
-                continue
-            for root, _dirnames, filenames in os.walk(guess):
-                if 'conf.py' in filenames:
-                    return root
-        return os.curdir
-
-    def finalize_options(self) -> None:
-        self.ensure_string_list('builder')
-
-        if self.source_dir is None:
-            self.source_dir = self._guess_source_dir()
-            self.announce('Using source directory %s' % self.source_dir)
-
-        self.ensure_dirname('source_dir')
-
-        if self.config_dir is None:
-            self.config_dir = self.source_dir
-
-        if self.build_dir is None:
-            build = self.get_finalized_command('build')
-            self.build_dir = os.path.join(abspath(build.build_base), 'sphinx')
-
-        self.doctree_dir = os.path.join(self.build_dir, 'doctrees')
-
-        self.builder_target_dirs = [
-            (builder, os.path.join(self.build_dir, builder))
-            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:
-            status_stream = StringIO()
-        else:
-            status_stream = sys.stdout  # type: ignore
-        confoverrides: dict[str, Any] = {}
-        if self.project:
-            confoverrides['project'] = self.project
-        if self.version:
-            confoverrides['version'] = self.version
-        if self.release:
-            confoverrides['release'] = self.release
-        if self.today:
-            confoverrides['today'] = self.today
-        if self.copyright:
-            confoverrides['copyright'] = self.copyright
-        if self.nitpicky:
-            confoverrides['nitpicky'] = self.nitpicky
-
-        for builder, builder_target_dir in self.builder_target_dirs:
-            app = None
-
-            try:
-                confdir = self.config_dir or self.source_dir
-                with patch_docutils(confdir), docutils_namespace():
-                    app = Sphinx(self.source_dir, self.config_dir,
-                                 builder_target_dir, self.doctree_dir,
-                                 builder, confoverrides, status_stream,
-                                 freshenv=self.fresh_env,
-                                 warningiserror=self.warning_is_error,
-                                 verbosity=self.verbosity, keep_going=self.keep_going)
-                    app.build(force_all=self.all_files)
-                    if app.statuscode:
-                        raise ExecError('caused by %s builder.' % app.builder.name)
-            except Exception as exc:
-                handle_exception(app, self, exc, sys.stderr)
-                if not self.pdb:
-                    raise SystemExit(1) from exc
-
-            if not self.link_index:
-                continue
-
-            src = app.config.root_doc + app.builder.out_suffix  # type: ignore
-            dst = app.builder.get_outfilename('index')  # type: ignore
-            os.symlink(src, dst)
diff --git a/tests/roots/test-basic/index.rst b/tests/roots/test-basic/index.rst
index 48407e643..af12ed683 100644
--- a/tests/roots/test-basic/index.rst
+++ b/tests/roots/test-basic/index.rst
@@ -29,4 +29,3 @@ Among its features are the following:
 * Flexible HTML output using the Jinja 2 templating engine
 * Various extensions are available, e.g. for automatic testing of snippets
   and inclusion of appropriately formatted docstrings
-* Setuptools integration
diff --git a/tests/roots/test-local-logo/index.rst b/tests/roots/test-local-logo/index.rst
index 48407e643..af12ed683 100644
--- a/tests/roots/test-local-logo/index.rst
+++ b/tests/roots/test-local-logo/index.rst
@@ -29,4 +29,3 @@ Among its features are the following:
 * Flexible HTML output using the Jinja 2 templating engine
 * Various extensions are available, e.g. for automatic testing of snippets
   and inclusion of appropriately formatted docstrings
-* Setuptools integration
diff --git a/tests/roots/test-remote-logo/index.rst b/tests/roots/test-remote-logo/index.rst
index 48407e643..af12ed683 100644
--- a/tests/roots/test-remote-logo/index.rst
+++ b/tests/roots/test-remote-logo/index.rst
@@ -29,4 +29,3 @@ Among its features are the following:
 * Flexible HTML output using the Jinja 2 templating engine
 * Various extensions are available, e.g. for automatic testing of snippets
   and inclusion of appropriately formatted docstrings
-* Setuptools integration