mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
2afa0b6627
At present, the 'builder' option for the setuptools integration only supports a single output format, typically HTML, like so: [build_sphinx] builder = man There is value in being able to specify multiple format, like so: [build_sphinx] builder = html man Make this possible. Signed-off-by: Stephen Finucane <stephen@that.guru>
179 lines
4.2 KiB
ReStructuredText
179 lines
4.2 KiB
ReStructuredText
.. _setuptools:
|
|
|
|
Setuptools integration
|
|
======================
|
|
|
|
Sphinx supports integration with setuptools and distutils through a custom
|
|
command - :class:`~sphinx.setup_command.BuildDoc`.
|
|
|
|
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 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
|
|
|
|
Once configured, call this by calling the relevant command on ``setup.py``::
|
|
|
|
$ python setup.py build_sphinx
|
|
|
|
Options for setuptools integration
|
|
----------------------------------
|
|
|
|
.. 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:: bash
|
|
|
|
$ python setup.py build_sphinx -E
|
|
|
|
.. 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:: bash
|
|
|
|
$ python setup.py build_sphinx -a
|
|
|
|
.. confval:: source-dir
|
|
|
|
The target source directory. This can be relative to the ``setup.py`` or
|
|
``setup.cfg`` file, or it can be absolute. Default is ``''``.
|
|
|
|
This can also be set by passing the `-s` flag to ``setup.py``:
|
|
|
|
.. code-block:: bash
|
|
|
|
$ python setup.py build_sphinx -s $SOURCE_DIR
|
|
|
|
.. 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 ``''``.
|
|
|
|
.. 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
|
|
``''``.
|
|
|
|
This can also be set by passing the `-c` flag to ``setup.py``:
|
|
|
|
.. code-block:: bash
|
|
|
|
$ python setup.py build_sphinx -c $CONFIG_DIR
|
|
|
|
.. versionadded:: 1.0
|
|
|
|
.. 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:: bash
|
|
|
|
$ python setup.py build_sphinx -b $BUILDER
|
|
|
|
.. versionchanged:: 1.6
|
|
This can now be a comma- or space-separated list of builders
|
|
|
|
.. 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:: bash
|
|
|
|
$ python setup.py build_sphinx -W
|
|
|
|
.. versionadded:: 1.5
|
|
|
|
.. confval:: project
|
|
|
|
The documented project's name. Default is ``''``.
|
|
|
|
.. versionadded:: 1.0
|
|
|
|
.. confval:: version
|
|
|
|
The short X.Y version. Default is ``''``.
|
|
|
|
.. versionadded:: 1.0
|
|
|
|
.. confval:: release
|
|
|
|
The full version, including alpha/beta/rc tags. Default is ``''``.
|
|
|
|
.. versionadded:: 1.0
|
|
|
|
.. confval:: today
|
|
|
|
How to format the current date, used as the replacement for ``|today|``.
|
|
Default is ``''``.
|
|
|
|
.. versionadded:: 1.0
|
|
|
|
.. confval:: link-index
|
|
|
|
A boolean that ensures index.html will be linked to the master doc. Default
|
|
is false.
|
|
|
|
This can also be set by passing the `-i` flag to ``setup.py``:
|
|
|
|
.. code-block:: bash
|
|
|
|
$ python setup.py build_sphinx -i
|
|
|
|
.. versionadded:: 1.0
|
|
|
|
.. confval:: copyright
|
|
|
|
The copyright string. Default is ``''``.
|
|
|
|
.. versionadded:: 1.3
|
|
|
|
.. confval:: pdb
|
|
|
|
A boolean to configure ``pdb`` on exception. Default is false.
|
|
|
|
.. versionadded:: 1.5
|