mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
29da4f9444
While this feature is somewhat documented in the API guide, there's nothing about this option in the main user guide. Given the lack of blogs and articles talking about this feature, along with the amount of projects that are only using the same copy-paste '[build_sphinx]' definition, I imagine this is an issue. Make the feature a little more accessible by adding a section to the main user guide that details (a) the fact the feature exists, (b) why you'd want to use it, and (c) how you can use it. Signed-off-by: Stephen Finucane <stephen@that.guru>
176 lines
4.1 KiB
ReStructuredText
176 lines
4.1 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 to use. Defaults is ``html``.
|
|
|
|
This can also be set by passing the `-b` flag to ``setup.py``:
|
|
|
|
.. code-block:: bash
|
|
|
|
$ python setup.py build_sphinx -b
|
|
|
|
.. 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
|