diff --git a/CHANGES b/CHANGES index 0b82096c27a..049019b33e2 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 19b8b2a2e57..8bf8d90a708 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 8029714df54..863af316543 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 ` + * - 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 6fe68dcddea..00000000000 --- 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 0f4c2221105..fd8cdd8bf8c 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 abfa269d823..0773f6030cb 100644 --- a/doc/usage/quickstart.rst +++ b/doc/usage/quickstart.rst @@ -332,7 +332,6 @@ More topics to be covered - :doc:`Other extensions `: - Static files - :doc:`Selecting a theme ` -- :doc:`/usage/advanced/setuptools` - :ref:`Templating ` - Using extensions - :ref:`Writing extensions ` diff --git a/pyproject.toml b/pyproject.toml index 6c2d707c722..424af4938f7 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 cbcdb2ff23b..00000000000 --- a/sphinx/setup_command.py +++ /dev/null @@ -1,192 +0,0 @@ -"""Setuptools/distutils commands to assist the building of sphinx documentation. - -:author: Sebastian Wiesner -""" - -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 48407e643c4..af12ed68398 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 48407e643c4..af12ed68398 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 48407e643c4..af12ed68398 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