IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

Remove the deprecated Setuptools integration (#11363)

Browse Source
This commit is contained in:
Adam Turner
2023-04-27 01:22:04 +01:00
committed by GitHub
parent 616ba29f28
commit 2a9e805206
11 changed files with 3 additions and 402 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
CHANGES
View File

@@ -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
----------

3
doc/conf.py
View File

@@ -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,

2
doc/extdev/deprecated.rst
View File

@@ -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

200
doc/usage/advanced/setuptools.rst
View File

@@ -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

1
doc/usage/index.rst
View File

@@ -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

1
doc/usage/quickstart.rst
View File

@@ -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>`

1
pyproject.toml
View File

@@ -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",

192
sphinx/setup_command.py
View File

@@ -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)

1
tests/roots/test-basic/index.rst
View File

@@ -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

1
tests/roots/test-local-logo/index.rst
View File

@@ -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

1
tests/roots/test-remote-logo/index.rst
View File

@@ -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