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, --jobs N
127 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 Changed in version 6.2: Add --jobs long option.
141 -c path
144 Don’t look for the conf.py in the source directory, but use the
145 given configuration directory instead. Note that various other
146 files and paths given by configuration values are expected to be
147 relative to the configuration directory, so they will have to be
148 present at this location too.
149 New in version 0.3.
151 -C Don’t look for a configuration file; only take options via the
154 -D option.
155 New in version 0.5.
157 -D setting=value
160 Override a configuration value set in the conf.py file. The
161 value must be a number, string, list or dictionary value.
162 For lists, you can separate elements with a comma like this: -D
164 html_theme_path=path1,path2.
165 For dictionary values, supply the setting name and key like
167 this: -D latex_elements.docclass=scrartcl.
168 For boolean values, use 0 or 1 as the value.
170 Changed in version 0.6: The value can now be a dictionary value.
172 Changed in version 1.3: The value can now also be a list value.
175 -A name=value
178 Make the name assigned to value in the HTML templates.
179 New in version 0.5.
181 -n Run in nit-picky mode. Currently, this generates warnings for
184 all missing references. See the config value nitpick_ignore for
185 a way to exclude some references as “known missing”.
186 -N Do not emit colored output.
188 -v Increase verbosity (loglevel). This option can be given up to
190 three times to get more debug logging output. It implies -T.
191 New in version 1.2.
193 -q Do not output anything on standard output, only write warnings
196 and errors to standard error.
197 -Q Do not output anything on standard output, also suppress warn‐
199 ings. Only errors are written to standard error.
200 -w file
202 Write warnings (and errors) to the given file, in addition to
203 standard error.
204 -W Turn warnings into errors. This means that the build stops at
206 the first warning and sphinx-build exits with exit status 1.
207 --keep-going
209 With -W option, keep going processing when getting warnings to
210 the end of build, and sphinx-build exits with exit status 1.
211 New in version 1.8.
213 -T Display the full traceback when an unhandled exception occurs.
216 Otherwise, only a summary is displayed and the traceback infor‐
217 mation is saved to a file for further analysis.
218 New in version 1.2.
220 -P (Useful for debugging only.) Run the Python debugger, pdb, if
223 an unhandled exception occurs while building.
224 -h, --help, --version
226 Display usage summary or Sphinx version.
227 New in version 1.2.
229 You can also give one or more filenames on the command line after the
232 source and build directories. Sphinx will then try to build only these
233 output files (and their dependencies).
234
236 The sphinx-build refers following environment variables:
237 MAKE A path to make command. A command name is also allowed.
239 sphinx-build uses it to invoke sub-build process on make-mode.
240 Makefile Options
242 The Makefile and make.bat files created by sphinx-quickstart usually
244 run sphinx-build only with the -b and -d options. However, they sup‐
245 port the following variables to customize behavior:
246 PAPER This sets the 'papersize' key of latex_elements: i.e. PAPER=a4
248 sets it to 'a4paper' and PAPER=letter to 'letterpaper'.
249 NOTE:
251 Usage of this environment variable got broken at Sphinx 1.5
252 as a4 or letter ended up as option to LaTeX document in place
253 of the needed a4paper, resp. letterpaper. Fixed at 1.7.7.
254 SPHINXBUILD
256 The command to use instead of sphinx-build.
257 BUILDDIR
259 The build directory to use instead of the one chosen in
260 sphinx-quickstart.
261 SPHINXOPTS
263 Additional options for sphinx-build. These options can also be
264 set via the shortcut variable O (capital ‘o’).
265 NO_COLOR
267 When set (regardless of value), sphinx-build will not use color
268 in terminal output. NO_COLOR takes precedence over FORCE_COLOR.
269 See no-color.org for other libraries supporting this community
270 standard.
271 New in version 4.5.0.
273 FORCE_COLOR
276 When set (regardless of value), sphinx-build will use color in
277 terminal output. NO_COLOR takes precedence over FORCE_COLOR.
278 New in version 4.5.0.
280
283 If any deprecation warning like RemovedInSphinxXXXWarning are displayed
284 when building a user’s document, some Sphinx extension is using depre‐
285 cated features. In that case, please report it to author of the exten‐
286 sion.
287 To disable the deprecation warnings, please set PYTHONWARNINGS= envi‐
289 ronment variable to your environment. For example:
290 • PYTHONWARNINGS= make html (Linux/Mac)
292 • export PYTHONWARNINGS= and do make html (Linux/Mac)
294 • set PYTHONWARNINGS= and do make html (Windows)
296 • modify your Makefile/make.bat and set the environment variable
298
300 sphinx-quickstart(1)
301
303 2007-2023, the Sphinx developers
3046.2.1 Jul 27, 2023 SPHINX-BUILD(1)