1SPHINX-BUILD(1)                     Sphinx                     SPHINX-BUILD(1)
2
3
4

NAME

6       sphinx-build - Sphinx documentation generator tool
7

SYNOPSIS

9       sphinx-build [options] <sourcedir> <outputdir> [filenames …]
10

DESCRIPTION

12       sphinx-build  generates documentation from the files in <sourcedir> and
13       places it in the <outputdir>.
14
15       sphinx-build looks for <sourcedir>/conf.py for the  configuration  set‐
16       tings.   sphinx-quickstart(1)  may  be used to generate template files,
17       including conf.py.
18
19       sphinx-build can create documentation in different formats.   A  format
20       is  selected by specifying the builder name on the command line; it de‐
21       faults to HTML.  Builders can also perform other tasks related to docu‐
22       mentation  processing.   For  a  list  of  available builders, refer to
23       sphinx-build -b.
24
25       By default, everything that is outdated is built.  Output only for  se‐
26       lected files can be built by specifying individual filenames.
27

OPTIONS

29       -b buildername
30              The  most important option: it selects a builder.  The most com‐
31              mon builders are:
32
33              html   Build HTML pages.  This is the default builder.
34
35              dirhtml
36                     Build HTML pages, but with a single directory  per  docu‐
37                     ment.   Makes for prettier URLs (no .html) if served from
38                     a webserver.
39
40              singlehtml
41                     Build a single HTML with the whole content.
42
43              htmlhelp, qthelp, devhelp, epub
44                     Build HTML files with additional information for building
45                     a documentation collection in one of these formats.
46
47              applehelp
48                     Build  an Apple Help Book.  Requires hiutil and codesign,
49                     which are not Open Source and presently only available on
50                     Mac OS X 10.6 and higher.
51
52              latex  Build  LaTeX  sources that can be compiled to a PDF docu‐
53                     ment using pdflatex.
54
55              man    Build manual pages in groff format for UNIX systems.
56
57              texinfo
58                     Build Texinfo files that can be processed into Info files
59                     using makeinfo.
60
61              text   Build plain text files.
62
63              gettext
64                     Build gettext-style message catalogs (.pot files).
65
66              doctest
67                     Run all doctests in the documentation, if the doctest ex‐
68                     tension is enabled.
69
70              linkcheck
71                     Check the integrity of all external links.
72
73              xml    Build Docutils-native XML files.
74
75              pseudoxml
76                     Build compact pretty-printed “pseudo-XML” files  display‐
77                     ing  the  internal structure of the intermediate document
78                     trees.
79
80              See Builders for a list of all  builders  shipped  with  Sphinx.
81              Extensions can add their own builders.
82
83       -M buildername
84              Alternative  to -b. Uses the Sphinx make_mode module, which pro‐
85              vides the same build functionality  as  a  default  Makefile  or
86              Make.bat.  In  addition  to  all  Sphinx Builders, the following
87              build pipelines are available:
88
89              latexpdf
90                     Build LaTeX files and run them through  pdflatex,  or  as
91                     per  latex_engine  setting.   If language is set to 'ja',
92                     will use automatically the platex/dvipdfmx latex  to  PDF
93                     pipeline.
94
95              info   Build Texinfo files and run them through makeinfo.
96
97              IMPORTANT:
98                 Sphinx only recognizes the -M option if it is placed first.
99
100              New in version 1.2.1.
101
102
103       -a     If  given, always write all output files. The default is to only
104              write output files for new and changed source files.  (This  may
105              not apply to all builders.)
106
107       -E     Don’t  use  a  saved  environment  (the  structure  caching  all
108              cross-references), but rebuild it completely.  The default is to
109              only  read  and  parse source files that are new or have changed
110              since the last run.
111
112       -t tag Define the tag tag.  This is relevant for only  directives  that
113              only include their content if this tag is set.
114
115              New in version 0.6.
116
117
118       -d path
119              Since  Sphinx  has  to read and parse all source files before it
120              can write an output file, the parsed source files are cached  as
121              “doctree pickles”.  Normally, these files are put in a directory
122              called .doctrees under the build directory; with this option you
123              can  select  a  different  cache  directory (the doctrees can be
124              shared between all builders).
125
126       -j N   Distribute the build over  N  processes  in  parallel,  to  make
127              building  on  multiprocessor machines more effective.  Note that
128              not all parts and not all  builders  of  Sphinx  can  be  paral‐
129              lelized.   If  auto argument is given, Sphinx uses the number of
130              CPUs as N.
131
132              New in version 1.2: This option should be considered  experimen‐
133              tal.
134
135
136              Changed in version 1.7: Support auto argument.
137
138
139       -c path
140              Don’t  look for the conf.py in the source directory, but use the
141              given configuration directory instead.  Note that various  other
142              files and paths given by configuration values are expected to be
143              relative to the configuration directory, so they will have to be
144              present at this location too.
145
146              New in version 0.3.
147
148
149       -C     Don’t  look  for a configuration file; only take options via the
150              -D option.
151
152              New in version 0.5.
153
154
155       -D setting=value
156              Override a configuration value set in  the  conf.py  file.   The
157              value must be a number, string, list or dictionary value.
158
159              For  lists, you can separate elements with a comma like this: -D
160              html_theme_path=path1,path2.
161
162              For dictionary values, supply the  setting  name  and  key  like
163              this: -D latex_elements.docclass=scrartcl.
164
165              For boolean values, use 0 or 1 as the value.
166
167              Changed in version 0.6: The value can now be a dictionary value.
168
169
170              Changed in version 1.3: The value can now also be a list value.
171
172
173       -A name=value
174              Make the name assigned to value in the HTML templates.
175
176              New in version 0.5.
177
178
179       -n     Run  in  nit-picky mode.  Currently, this generates warnings for
180              all missing references.  See the config value nitpick_ignore for
181              a way to exclude some references as “known missing”.
182
183       -N     Do not emit colored output.
184
185       -v     Increase  verbosity  (loglevel).  This option can be given up to
186              three times to get more debug logging output.  It implies -T.
187
188              New in version 1.2.
189
190
191       -q     Do not output anything on standard output, only  write  warnings
192              and errors to standard error.
193
194       -Q     Do  not  output anything on standard output, also suppress warn‐
195              ings.  Only errors are written to standard error.
196
197       -w file
198              Write warnings (and errors) to the given file,  in  addition  to
199              standard error.
200
201       -W     Turn  warnings  into errors.  This means that the build stops at
202              the first warning and sphinx-build exits with exit status 1.
203
204       --keep-going
205              With -W option, keep going processing when getting  warnings  to
206              the end of build, and sphinx-build exits with exit status 1.
207
208              New in version 1.8.
209
210
211       -T     Display  the  full traceback when an unhandled exception occurs.
212              Otherwise, only a summary is displayed and the traceback  infor‐
213              mation is saved to a file for further analysis.
214
215              New in version 1.2.
216
217
218       -P     (Useful  for  debugging only.)  Run the Python debugger, pdb, if
219              an unhandled exception occurs while building.
220
221       -h, --help, --version
222              Display usage summary or Sphinx version.
223
224              New in version 1.2.
225
226
227       You can also give one or more filenames on the command line  after  the
228       source  and build directories. Sphinx will then try to build only these
229       output files (and their dependencies).
230

ENVIRONMENT VARIABLES

232       The sphinx-build refers following environment variables:
233
234       MAKE   A path to  make  command.   A  command  name  is  also  allowed.
235              sphinx-build uses it to invoke sub-build process on make-mode.
236
237       Makefile Options
238
239       The  Makefile  and  make.bat files created by sphinx-quickstart usually
240       run sphinx-build only with the -b and -d options.  However,  they  sup‐
241       port the following variables to customize behavior:
242
243       PAPER  This  sets  the 'papersize' key of latex_elements: i.e. PAPER=a4
244              sets it to 'a4paper' and PAPER=letter to 'letterpaper'.
245
246              NOTE:
247                 Usage of this environment variable got broken at  Sphinx  1.5
248                 as a4 or letter ended up as option to LaTeX document in place
249                 of the needed a4paper, resp. letterpaper.  Fixed at 1.7.7.
250
251       SPHINXBUILD
252              The command to use instead of sphinx-build.
253
254       BUILDDIR
255              The build  directory  to  use  instead  of  the  one  chosen  in
256              sphinx-quickstart.
257
258       SPHINXOPTS
259              Additional  options  for sphinx-build. These options can also be
260              set via the shortcut variable O (capital ‘o’).
261
262       NO_COLOR
263              When set (regardless of value), sphinx-build  will not use color
264              in  terminal output. NO_COLOR takes precedence over FORCE_COLOR.
265              See no-color.org for other libraries supporting  this  community
266              standard.
267
268              New in version 4.5.0.
269
270
271       FORCE_COLOR
272              When  set  (regardless of value), sphinx-build will use color in
273              terminal output. NO_COLOR takes precedence over FORCE_COLOR.
274
275              New in version 4.5.0.
276
277

DEPRECATION WARNINGS

279       If any deprecation warning like RemovedInSphinxXXXWarning are displayed
280       when  building a user’s document, some Sphinx extension is using depre‐
281       cated features. In that case, please report it to author of the  exten‐
282       sion.
283
284       To  disable  the deprecation warnings, please set PYTHONWARNINGS= envi‐
285       ronment variable to your environment. For example:
286
287PYTHONWARNINGS= make html (Linux/Mac)
288
289export PYTHONWARNINGS= and do make html (Linux/Mac)
290
291set PYTHONWARNINGS= and do make html (Windows)
292
293       • modify your Makefile/make.bat and set the environment variable
294

SEE ALSO

296       sphinx-quickstart(1)
297
299       2007-2023, the Sphinx developers
300
301
302
303
3045.3.0                            Jan 31, 2023                  SPHINX-BUILD(1)
Impressum