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
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
|
.. -*- rst-mode -*-
.. Help text generated with ``rst2html_trans --help``.
.. contents::
Usage
=====
rst2html_trans.py [options] [<source> [<destination>]]
Generates (X)HTML documents from standalone reStructuredText sources that do
not require a CSS stylesheet. Reads from <source> (default is stdin) and
writes to <destination> (default is stdout).
options
=======
General Docutils Options
------------------------
--title=TITLE Specify the document title as metadata (not part of
the document body). Overrides a document-provided
title. There is no default.
--generator, -g Include a "Generated by Docutils" credit and link at
the end of the document.
--no-generator Do not include a generator credit.
--date, -d Include the date at the end of the document (UTC).
--time, -t Include the time & date at the end of the document
(UTC).
--no-datestamp Do not include a datestamp of any kind.
--source-link, -s Include a "View document source" link (relative to
destination).
--source-url=<URL> Use the supplied <URL> verbatim for a "View document
source" link; implies --source-link.
--no-source-link Do not include a "View document source" link.
--toc-entry-backlinks Enable backlinks from section headers to table of
contents entries. This is the default.
--toc-top-backlinks Enable backlinks from section headers to the top of
the table of contents.
--no-toc-backlinks Disable backlinks to the table of contents.
--footnote-backlinks Enable backlinks from footnotes and citations to their
references. This is the default.
--no-footnote-backlinks
Disable backlinks from footnotes and citations.
--section-numbering Enable Docutils section numbering (default: enabled).
--no-section-numbering Disable Docutils section numbering (default: enabled).
--strip-comments Remove comment elements from the document tree
(default: leave them).
--leave-comments Leave comment elements in the document tree (this is
the default).
--report=<level>, -r <level>
Set verbosity threshold; report system messages at or
higher than <level> (by name or number: "info" or "1",
warning/2, error/3, severe/4; also, "none" or "5").
Default is 2 (warning).
--verbose, -v Report all system messages, info-level and higher.
(Same as "--report=info".)
--quiet, -q Do not report any system messages. (Same as "--
report=none".)
--halt=<level> Set the threshold (<level>) at or above which system
messages are converted to exceptions, halting
execution immediately by exiting (or propagating the
exception if --traceback set). Levels as in --report.
Default is 4 (severe).
--strict Same as "--halt=info": halt processing at the
slightest problem.
--exit-status=<level> Enable a non-zero exit status for normal exit if non-
halting system messages (at or above <level>) were
generated. Levels as in --report. Default is 5
(disabled). Exit status is the maximum system message
level plus 10 (11 for INFO, etc.).
--debug Report debug-level system messages and generate
diagnostic output.
--no-debug Do not report debug-level system messages or generate
diagnostic output.
--warnings=<file> Send the output of system messages (warnings) to
<file>.
--traceback Enable Python tracebacks when halt-level system
messages and other exceptions occur. Useful for
debugging, and essential for issue reports.
--no-traceback Disable Python tracebacks when errors occur; report
just the error instead. This is the default.
--input-encoding=<name[:handler]>, -i <name[:handler]>
Specify the encoding of input text. Default is
locale-dependent. Optionally also specify the error
handler for undecodable characters, after a colon
(":"); default is "strict". (See "--intput-encoding-
error-handler".)
--input-encoding-error-handler=INPUT_ENCODING_ERROR_HANDLER
Specify the error handler for undecodable characters
in the input. Acceptable values include "strict",
"ignore", and "replace". Default is "strict".
Usually specified as part of --input-encoding.
--output-encoding=<name[:handler]>, -o <name[:handler]>
Specify the text encoding for output. Default is
UTF-8. Optionally also specify the error handler for
unencodable characters, after a colon (":"); default
is "strict". (See "--output-encoding-error-handler".)
--output-encoding-error-handler=OUTPUT_ENCODING_ERROR_HANDLER
Specify the error handler for unencodable characters
in the output. Acceptable values include "strict",
"ignore", "replace", "xmlcharrefreplace", and
"backslashreplace" (in Python 2.3+). Default is
"strict". Usually specified as part of --output-
encoding.
--error-encoding=<name[:handler]>, -e <name[:handler]>
Specify the text encoding for error output. Default
is ASCII. Optionally also specify the error handler
for unencodable characters, after a colon (":");
default is "backslashreplace". (See "--output-
encoding-error-handler".)
--error-encoding-error-handler=ERROR_ENCODING_ERROR_HANDLER
Specify the error handler for unencodable characters
in error output. See --output-encoding-error-handler
for acceptable values. Default is "backslashreplace".
Usually specified as part of --error-encoding.
--language=<name>, -l <name>
Specify the language of input text (ISO 639 2-letter
identifier). Default is "en" (English).
--record-dependencies=<file>
Write dependencies (caused e.g. by file inclusions) to
<file>. Useful in conjunction with programs like
"make".
--config=<file> Read configuration settings from <file>, if it exists.
--version, -V Show this program's version number and exit.
--help, -h Show this help message and exit.
reStructuredText Parser Options
-------------------------------
--pep-references Recognize and link to standalone PEP references (like
"PEP 258").
--pep-base-url=<URL> Base URL for PEP references (default
"http://www.python.org/peps/").
--rfc-references Recognize and link to standalone RFC references (like
"RFC 822").
--rfc-base-url=<URL> Base URL for RFC references (default
"http://www.faqs.org/rfcs/").
--tab-width=<width> Set number of spaces for tab expansion (default 8).
--trim-footnote-reference-space
Remove spaces before footnote references.
--leave-footnote-reference-space
Leave spaces before footnote references.
--no-file-insertion Disable directives that insert the contents of
external file ("include" & "raw"); replaced with a
"warning" system message.
--file-insertion-enabled
Enable directives that insert the contents of external
file ("include" & "raw"). Enabled by default.
--no-raw Disable the "raw" directives; replaced with a
"warning" system message.
--raw-enabled Enable the "raw" directive. Enabled by default.
Standalone Reader
-----------------
--no-doc-title Disable the promotion of a lone top-level section
title to document title (and subsequent section title
to document subtitle promotion; enabled by default).
--no-doc-info Disable the bibliographic field list transform
(enabled by default).
--section-subtitles Activate the promotion of lone subsection titles to
section subtitles (disabled by default).
--no-section-subtitles Deactivate the promotion of lone subsection titles.
HTML-Specific Options
---------------------
--stylesheet=<URL> Specify a stylesheet URL, used verbatim. Overrides
--stylesheet-path.
--stylesheet-path=<file>
Specify a stylesheet file, relative to the current
working directory. The path is adjusted relative to
the output HTML file. Overrides --stylesheet.
Default: "../../../../lib/python2.4/site-
packages/docutils/writers/html4css1/html4css1.css"
--embed-stylesheet Embed the stylesheet in the output HTML file. The
stylesheet file must be accessible during processing
(--stylesheet-path is recommended). This is the
default.
--link-stylesheet Link to the stylesheet in the output HTML file.
Default: embed the stylesheet, do not link to it.
--initial-header-level=<level>
Specify the initial header level. Default is 1 for
"<h1>". Does not affect document title & subtitle
(see --no-doc-title).
--field-name-limit=<level>
Specify the maximum width (in characters) for one-
column field names. Longer field names will span an
entire row of the table used to render the field list.
Default is 14 characters. Use 0 for "no limit".
--option-limit=<level> Specify the maximum width (in characters) for options
in option lists. Longer options will span an entire
row of the table used to render the option list.
Default is 14 characters. Use 0 for "no limit".
--footnote-references=<format>
Format for footnote references: one of "superscript"
or "brackets". Default is "brackets".
--attribution=<format> Format for block quote attributions: one of "dash"
(em-dash prefix), "parentheses"/"parens", or "none".
Default is "dash".
--compact-lists Remove extra vertical whitespace between items of
"simple" bullet lists and enumerated lists. Default:
enabled.
--no-compact-lists Disable compact simple bullet and enumerated lists.
--compact-field-lists Remove extra vertical whitespace between items of
simple field lists. Default: enabled.
--no-compact-field-lists
Disable compact simple field lists.
--no-xml-declaration Omit the XML declaration. Use with caution.
--cloak-email-addresses
Obfuscate email addresses to confuse harvesters while
still keeping email links usable with standards-
compliant browsers.
|
