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 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 By default, everything that is outdated is built. Output only for se‐
26 lected files can be built by specifying individual filenames.
27
29 -b buildername
30 The most important option: it selects a builder. The most com‐
31 mon builders are:
32 html Build HTML pages. This is the default builder.
34 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 singlehtml
41 Build a single HTML with the whole content.
42 htmlhelp, qthelp, devhelp, epub
44 Build HTML files with additional information for building
45 a documentation collection in one of these formats.
46 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 latex Build LaTeX sources that can be compiled to a PDF docu‐
53 ment using pdflatex.
54 man Build manual pages in groff format for UNIX systems.
56 texinfo
58 Build Texinfo files that can be processed into Info files
59 using makeinfo.
60 text Build plain text files.
62 gettext
64 Build gettext-style message catalogs (.pot files).
65 doctest
67 Run all doctests in the documentation, if the doctest ex‐
68 tension is enabled.
69 linkcheck
71 Check the integrity of all external links.
72 xml Build Docutils-native XML files.
74 pseudoxml
76 Build compact pretty-printed “pseudo-XML” files display‐
77 ing the internal structure of the intermediate document
78 trees.
79 See Builders for a list of all builders shipped with Sphinx.
81 Extensions can add their own builders.
82 -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 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 info Build Texinfo files and run them through makeinfo.
96 IMPORTANT:
98 Sphinx only recognizes the -M option if it is placed first.
99 New in version 1.2.1.
101 -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 -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 -t tag Define the tag tag. This is relevant for only directives that
113 only include their content if this tag is set.
114 New in version 0.6.
116 -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 -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 New in version 1.2: This option should be considered experimen‐
133 tal.
134 Changed in version 1.7: Support auto argument.
137 -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 New in version 0.3.
147 -C Don’t look for a configuration file; only take options via the
150 -D option.
151 New in version 0.5.
153 -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 For lists, you can separate elements with a comma like this: -D
160 html_theme_path=path1,path2.
161 For dictionary values, supply the setting name and key like
163 this: -D latex_elements.docclass=scrartcl.
164 For boolean values, use 0 or 1 as the value.
166 Changed in version 0.6: The value can now be a dictionary value.
168 Changed in version 1.3: The value can now also be a list value.
171 -A name=value
174 Make the name assigned to value in the HTML templates.
175 New in version 0.5.
177 -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 -N Do not emit colored output.
184 -v Increase verbosity (loglevel). This option can be given up to
186 three times to get more debug logging output. It implies -T.
187 New in version 1.2.
189 -q Do not output anything on standard output, only write warnings
192 and errors to standard error.
193 -Q Do not output anything on standard output, also suppress warn‐
195 ings. Only errors are written to standard error.
196 -w file
198 Write warnings (and errors) to the given file, in addition to
199 standard error.
200 -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 --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 New in version 1.8.
209 -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 New in version 1.2.
216 -P (Useful for debugging only.) Run the Python debugger, pdb, if
219 an unhandled exception occurs while building.
220 -h, --help, --version
222 Display usage summary or Sphinx version.
223 New in version 1.2.
225 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
232 The sphinx-build refers following environment variables:
233 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 Makefile Options
238 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 PAPER This sets the 'papersize' key of latex_elements: i.e. PAPER=a4
244 sets it to 'a4paper' and PAPER=letter to 'letterpaper'.
245 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 SPHINXBUILD
252 The command to use instead of sphinx-build.
253 BUILDDIR
255 The build directory to use instead of the one chosen in
256 sphinx-quickstart.
257 SPHINXOPTS
259 Additional options for sphinx-build. These options can also be
260 set via the shortcut variable O (capital ‘o’).
261 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 New in version 4.5.0.
269 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 New in version 4.5.0.
276
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 To disable the deprecation warnings, please set PYTHONWARNINGS= envi‐
285 ronment variable to your environment. For example:
286 • PYTHONWARNINGS= make html (Linux/Mac)
288 • export PYTHONWARNINGS= and do make html (Linux/Mac)
290 • set PYTHONWARNINGS= and do make html (Windows)
292 • modify your Makefile/make.bat and set the environment variable
294
296 sphinx-quickstart(1)
297
299 2007-2023, the Sphinx developers
3005.3.0 Jan 31, 2023 SPHINX-BUILD(1)