1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
|
.. _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'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
----------------------------------
.. 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. 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:: 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 ``./build/sphinx``.
.. 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:: 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:: 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
.. confval:: pdb
A boolean to configure ``pdb`` on exception. Default is false.
.. versionadded:: 1.5
|
