Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Remove the build_sphinx command #10008

Closed
wants to merge 1 commit into from
Closed

Remove the build_sphinx command #10008

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
3 changes: 2 additions & 1 deletion CHANGES
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ Dependencies
Incompatible changes
--------------------

* #9595: ``build_sphinx`` subcommand for distutils/setuptools has been removed.
* #9962: texinfo: Customizing styles of emphasized text via ``@definfoenclose``
command was not supported because the command was deprecated since texinfo 6.8
* #2068: :confval:`intersphinx_disabled_reftypes` has changed default value
Expand Down Expand Up @@ -886,7 +887,7 @@ Bugs fixed
inside function type signatures
* #8780: LaTeX: long words in narrow columns may not be hyphenated
* #8788: LaTeX: ``\titleformat`` last argument in sphinx.sty should be
bracketed, not braced (and is anyhow not needed)
bracketed, not braced (and is anyhow not needed)
* #8849: LaTex: code-block printed out of margin (see the opt-in LaTeX syntax
boolean :ref:`verbatimforcewraps <latexsphinxsetupforcewraps>` for use via
the :ref:`'sphinxsetup' <latexsphinxsetup>` key of ``latex_elements``)
Expand Down
3 changes: 0 additions & 3 deletions doc/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -146,9 +146,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,
Expand Down
202 changes: 16 additions & 186 deletions doc/usage/advanced/setuptools.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,194 +3,24 @@
Setuptools integration
======================

Sphinx supports integration with setuptools and distutils through a custom
command - :class:`~sphinx.setup_command.BuildDoc`.
.. versionremoved:: 5.0

Using setuptools integration
----------------------------
Sphinx 0.5 to 4.x used to support an integration with distutils (and,
by extension, setuptools) through a custom ``build_sphinx`` command.

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.
This support was removed in 5.0, since:

For instance, from ``setup.py``::
- this was built using ``distutils``, which has been deprecated
in Python 3.10, according to :pep:`632`.
- this extended the ``setup.py``-based interface, which
`is considered deprecated <setup.py-deprecated>` by the maintainers
of ``setuptools`` and ``distutils``.
- this did not have feature-parity with the ``sphinx-build`` command
line script, which caused subtle issues and additional maintenance
workload (for Sphinx maintainers as well as downstream users) due to
these behaviour differences.

# this is only necessary when not using setuptools/distribute
from sphinx.setup_command import BuildDoc
cmdclass = {'build_sphinx': BuildDoc}
Projects which depend upon this integration should switch to using
``sphinx-build`` directly.

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
.. _setup.py-deprecated: https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html
4 changes: 0 additions & 4 deletions setup.cfg
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,9 +9,6 @@ tag_date = true
release = egg_info -Db ''
upload = upload --sign --identity=36580288

[build_sphinx]
warning-is-error = 1

[extract_messages]
mapping_file = babel.cfg
output_file = sphinx/locale/sphinx.pot
Expand Down Expand Up @@ -63,7 +60,6 @@ filterwarnings =
ignore::ImportWarning:importlib._bootstrap
markers =
apidoc
setup_command
testpaths = tests

[coverage:run]
Expand Down
4 changes: 0 additions & 4 deletions setup.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -210,7 +210,6 @@ def _run_domain_js(self, domain):
'Programming Language :: Python :: 3.10',
'Programming Language :: Python :: Implementation :: CPython',
'Programming Language :: Python :: Implementation :: PyPy',
'Framework :: Setuptools Plugin',
'Framework :: Sphinx',
'Framework :: Sphinx :: Extension',
'Framework :: Sphinx :: Theme',
Expand Down Expand Up @@ -241,9 +240,6 @@ def _run_domain_js(self, domain):
'sphinx-apidoc = sphinx.ext.apidoc:main',
'sphinx-autogen = sphinx.ext.autosummary.generate:main',
],
'distutils.commands': [
'build_sphinx = sphinx.setup_command:BuildDoc',
],
},
python_requires=">=3.6",
install_requires=install_requires,
Expand Down