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
|
.TH sphinx-build 1 "Aug 2010" "Sphinx 0.6.6" "User Commands"
.SH NAME
sphinx-build \- Sphinx documentation generator tool
.SH SYNOPSIS
.B sphinx-build
[\fIoptions\fR] <\fIsourcedir\fR> <\fIoutdir\fR> [\fIfilenames\fR...]
.SH DESCRIPTION
\fBsphinx-build\fR generates documentation from the files in \fIsourcedir\fR and places it
to the \fIoutdir\fR.
\fBsphinx-build\fR reads \fIsourcedir\fR/conf.py for the configuration settings.
\fBsphinx-quickstart\fR(1)
may be used to generate template files, including conf.py.
\fBsphinx-build\fR can create documentation in different formats.
The output format is selected by specifying builder in command line and
defaults to HTML.
Builders can also perform other tasks related to the documentation
processing.
List of available builders:
.TP
\fBhtml\fR
Build HTML pages. This is the default builder.
.TP
\fBdirhtml\fR
Build HTML pages, but with a single directory per document.
.TP
\fBhtmlhelp\fR, \fBqthelp\fR
Build HTML pages with additional information for building a documentation collection in one of these formats.
.TP
\fBlatex\fR
Build LaTeX sources that can be compiled to a PDF document using \fBpdflatex\fR.
This builder uses the PAPER environment variable (e.g. PAPER=a4 or PAPER=letter) if available.
.TP
\fBtext\fR
Build plain text files.
.TP
\fBchanges\fR
Show changed/added/deprecated items since last documentation generation.
.TP
\fBlinkcheck\fR
Check the integrity of all external links in documentation.
.TP
\fBpickle\fR, \fBjson\fR
Produce a directory with pickle/JSON files containing mostly HTML fragments and TOC information, for use of a web application (or a custom postprocessing tool) that doesn't use the standard HTML templates.
.SH OPTIONS
.TP
\fB-b\fR \fIbuilder\fR
Select a builder. The default is \fBhtml\fR. See the full list of builders above.
.TP
\fIfilename\fR
Only generate documentation from the source file specified.
Additionally, this option forces regeneration.
.TP
\fB-a\fR
Write all output files.
(The default is to only write output files for new and changed source files.)
.TP
\fB-E\fR
Don't use a saved environment (the structure caching all
cross-references), but rebuild completely.
(The default is to only read and parse source files that are new or have
changed since the last run.)
.TP
\fB-t\fR \fItag\fR
Define the \fItag\fR. This is relevant for \[oq]only\[cq] directives that only include their content if this tag is set.
.TP
\fB-d\fR \fIpath\fR
Select cache directory. The default is \fIoutdir\fP/.doctrees/.
.TP
\fB-c\fR \fIpath\fR
Don't look for the conf.py in the \fIsourcedir\fR, but use the given configuration directory instead. Various other files and paths given by configuration values are expected to be relative to the configuration directory, so they will have to be present at this location too.
.TP
\fB-C\fR
Don't look for a configuration file; only take options via the \fB-D\fR option.
.TP
\fB-D\fR \fIsetting\fR=\fIvalue\fR
Override a configuration value set in the \fBconf.py\fR file.
.TP
\fB-A\fR \fIname\fR=\fIvalue\fR
Make the \fIname\fR assigned to \fIvalue\fR in the HTML templates.
.TP
\fB-N\fR
Do not emit colored output
.TP
\fB-q\fR
Do not output anything on standard output, only write warnings and errors to standard error.
.TP
\fB-Q\fR
Do not output anything on standard output, also suppress warnings. Only errors are written to standard error.
.TP
\fB-w\fR \fIfile\fR
Write warnings (and errors) to the given file, in addition to standard error.
.TP
\fB-W\fR
Turn warnings into errors. This means that the build stops at the first warning and \fBsphinx-build\fR exits with exit status 1.
.TP
\fB-P\fR
Run the Python debugger, \fBpdb\fR, if an unhandled exception occurs while building.
.SH "SEE ALSO"
\fBsphinx-quickstart\fR(1)
.PP
The full documentation for
.B Sphinx
is installed to
.B /usr/share/doc/python-sphinx
.
.SH AUTHOR
Georg Brandl <georg@python.org>, Armin Ronacher <armin.ronacher@active-4.com> et
al.
.PP
This manual page was written by Mikhail Gusarov <dottedmag@dottedmag.net>, for
the Debian project (but may be used by others).
|
