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.