1SPHINX-BUILD(1) Sphinx SPHINX-BUILD(1)
2
6 sphinx-build - Sphinx documentation generator tool
7
9 sphinx-build [options] <sourcedir> <outputdir> [filenames …]
10
12 sphinx-build generates documentation from the files in <sourcedir> and
13 places it in the <outputdir>.
14 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 sphinx-build can create documentation in different formats. A format
20 is selected by specifying the builder name on the command line; it
21 defaults to HTML. Builders can also perform other tasks related to
22 documentation processing.
23 By default, everything that is outdated is built. Output only for
25 selected files can be built by specifying individual filenames.
26 For a list of available options, refer to sphinx-build -b.
28
30 -b buildername
31 The most important option: it selects a builder. The most com‐
32 mon builders are:
33 html Build HTML pages. This is the default builder.
35 dirhtml
37 Build HTML pages, but with a single directory per docu‐
38 ment. Makes for prettier URLs (no .html) if served from
39 a webserver.
40 singlehtml
42 Build a single HTML with the whole content.
43 htmlhelp, qthelp, devhelp, epub
45 Build HTML files with additional information for building
46 a documentation collection in one of these formats.
47 applehelp
49 Build an Apple Help Book. Requires hiutil and codesign,
50 which are not Open Source and presently only available on
51 Mac OS X 10.6 and higher.
52 latex Build LaTeX sources that can be compiled to a PDF docu‐
54 ment using pdflatex.
55 man Build manual pages in groff format for UNIX systems.
57 texinfo
59 Build Texinfo files that can be processed into Info files
60 using makeinfo.
61 text Build plain text files.
63 gettext
65 Build gettext-style message catalogs (.pot files).
66 doctest
68 Run all doctests in the documentation, if the doctest
69 extension is enabled.
70 linkcheck
72 Check the integrity of all external links.
73 xml Build Docutils-native XML files.
75 pseudoxml
77 Build compact pretty-printed “pseudo-XML” files display‐
78 ing the internal structure of the intermediate document
79 trees.
80 See /usage/builders/index for a list of all builders shipped
82 with Sphinx. Extensions can add their own builders.
83 -M buildername
85 Alternative to -b. Uses the Sphinx make_mode module, which pro‐
86 vides the same build functionality as a default Makefile or
87 Make.bat. In addition to all Sphinx /usage/builders/index, the
88 following build pipelines are available:
89 latexpdf
91 Build LaTeX files and run them through pdflatex, or as
92 per latex_engine setting. If language is set to 'ja',
93 will use automatically the platex/dvipdfmx latex to PDF
94 pipeline.
95 info Build Texinfo files and run them through makeinfo.
97 IMPORTANT:
99 Sphinx only recognizes the -M option if it is placed first.
100 New in version 1.2.1.
102 -a If given, always write all output files. The default is to only
105 write output files for new and changed source files. (This may
106 not apply to all builders.)
107 -E Don’t use a saved environment (the structure caching all
109 cross-references), but rebuild it completely. The default is to
110 only read and parse source files that are new or have changed
111 since the last run.
112 -t tag Define the tag tag. This is relevant for only directives that
114 only include their content if this tag is set.
115 New in version 0.6.
117 -d path
120 Since Sphinx has to read and parse all source files before it
121 can write an output file, the parsed source files are cached as
122 “doctree pickles”. Normally, these files are put in a directory
123 called .doctrees under the build directory; with this option you
124 can select a different cache directory (the doctrees can be
125 shared between all builders).
126 -j N Distribute the build over N processes in parallel, to make
128 building on multiprocessor machines more effective. Note that
129 not all parts and not all builders of Sphinx can be paral‐
130 lelized. If auto argument is given, Sphinx uses the number of
131 CPUs as N.
132 New in version 1.2: This option should be considered experimen‐
134 tal.
135 Changed in version 1.7: Support auto argument.
138 -c path
141 Don’t look for the conf.py in the source directory, but use the
142 given configuration directory instead. Note that various other
143 files and paths given by configuration values are expected to be
144 relative to the configuration directory, so they will have to be
145 present at this location too.
146 New in version 0.3.
148 -C Don’t look for a configuration file; only take options via the
151 -D option.
152 New in version 0.5.
154 -D setting=value
157 Override a configuration value set in the conf.py file. The
158 value must be a number, string, list or dictionary value.
159 For lists, you can separate elements with a comma like this: -D
161 html_theme_path=path1,path2.
162 For dictionary values, supply the setting name and key like
164 this: -D latex_elements.docclass=scrartcl.
165 For boolean values, use 0 or 1 as the value.
167 Changed in version 0.6: The value can now be a dictionary value.
169 Changed in version 1.3: The value can now also be a list value.
172 -A name=value
175 Make the name assigned to value in the HTML templates.
176 New in version 0.5.
178 -n Run in nit-picky mode. Currently, this generates warnings for
181 all missing references. See the config value nitpick_ignore for
182 a way to exclude some references as “known missing”.
183 -N Do not emit colored output.
185 -v Increase verbosity (loglevel). This option can be given up to
187 three times to get more debug logging output. It implies -T.
188 New in version 1.2.
190 -q Do not output anything on standard output, only write warnings
193 and errors to standard error.
194 -Q Do not output anything on standard output, also suppress warn‐
196 ings. Only errors are written to standard error.
197 -w file
199 Write warnings (and errors) to the given file, in addition to
200 standard error.
201 -W Turn warnings into errors. This means that the build stops at
203 the first warning and sphinx-build exits with exit status 1.
204 --keep-going
206 With -W option, keep going processing when getting warnings to
207 the end of build, and sphinx-build exits with exit status 1.
208 New in version 1.8.
210 -T Display the full traceback when an unhandled exception occurs.
213 Otherwise, only a summary is displayed and the traceback infor‐
214 mation is saved to a file for further analysis.
215 New in version 1.2.
217 -P (Useful for debugging only.) Run the Python debugger, pdb, if
220 an unhandled exception occurs while building.
221 -h, --help, --version
223 Display usage summary or Sphinx version.
224 New in version 1.2.
226 You can also give one or more filenames on the command line after the
229 source and build directories. Sphinx will then try to build only these
230 output files (and their dependencies).
231
233 The sphinx-build refers following environment variables:
234 MAKE A path to make command. A command name is also allowed.
236 sphinx-build uses it to invoke sub-build process on make-mode.
237 Makefile Options
239 The Makefile and make.bat files created by sphinx-quickstart usually
241 run sphinx-build only with the -b and -d options. However, they sup‐
242 port the following variables to customize behavior:
243 PAPER This sets the 'papersize' key of latex_elements: i.e. PAPER=a4
245 sets it to 'a4paper' and PAPER=letter to 'letterpaper'.
246 NOTE:
248 Usage of this environment variable got broken at Sphinx 1.5
249 as a4 or letter ended up as option to LaTeX document in place
250 of the needed a4paper, resp. letterpaper. Fixed at 1.7.7.
251 SPHINXBUILD
253 The command to use instead of sphinx-build.
254 BUILDDIR
256 The build directory to use instead of the one chosen in
257 sphinx-quickstart.
258 SPHINXOPTS
260 Additional options for sphinx-build. These options can also be
261 set via the shortcut variable O (capital ‘o’).
262
264 If any deprecation warning like RemovedInSphinxXXXWarning are displayed
265 when building a user’s document, some Sphinx extension is using depre‐
266 cated features. In that case, please report it to author of the exten‐
267 sion.
268 To disable the deprecation warnings, please set PYTHONWARNINGS= envi‐
270 ronment variable to your environment. For example:
271 · PYTHONWARNINGS= make html (Linux/Mac)
273 · export PYTHONWARNINGS= and do make html (Linux/Mac)
275 · set PYTHONWARNINGS= and do make html (Windows)
277 · modify your Makefile/make.bat and set the environment variable
279
281 sphinx-quickstart(1)
282
284 2007-2020, Georg Brandl and the Sphinx team
2852.2.2 Jan 30, 2020 SPHINX-BUILD(1)