| Author: | David Goodger |
|---|---|
| Contact: | goodger@python.org |
| Revision: | 6156 |
| Date: | 2009-10-08 |
| Copyright: | This document has been placed in the public domain. |
Contents
Configuration files are used for persistent customization; they can be set once and take effect every time you use a front-end tool. Configuration file settings override the built-in defaults, and command-line options override all.
By default, Docutils checks the following places for configuration files, in the following order:
If more than one configuration file is found, all will be read but later entries will override earlier ones. For example, a "stylesheet" entry in a user-specific configuration file will override a "stylesheet" entry in the system-wide file.
The default implicit config file paths can be overridden by the DOCUTILSCONFIG environment variable. DOCUTILSCONFIG should contain a colon-separated (semicolon-separated on Windows) sequence of config file paths to search for; leave it empty to disable implicit config files altogether. Tilde-expansion is performed on paths. Paths are interpreted relative to the current working directory. Empty path items are ignored.
In addition, a configuration file may be explicitly specified with the "--config" command-line option. This configuration file is read after the three implicit ones listed above (or the ones defined by the DOCUTILSCONFIG environment variable), and its entries will have priority.
Configuration files are UTF-8-encoded text files. The ConfigParser.py module from Python's standard library is used to read them. From its documentation:
The configuration file consists of sections, lead by a "[section]" header and followed by "name: value" entries, with continuations in the style of RFC 822; "name=value" is also accepted. Note that leading whitespace is removed from values. ... Lines beginning with "#" or ";" are ignored and may be used to provide comments.
Note
No format string interpolation is done.
Configuration file entry names correspond to internal runtime settings. Underscores ("_") and hyphens ("-") can be used interchangably in entry names; hyphens are automatically converted to underscores.
For on/off switch settings (booleans), the following values are recognized:
This is the contents of the tools/docutils.conf configuration file supplied with Docutils:
# These entries affect all processing: [general] source-link: yes datestamp: %Y-%m-%d %H:%M UTC generator: on # These entries affect HTML output: [html4css1 writer] # Required for docutils-update, the website build system: stylesheet-path: ../docutils/writers/html4css1/html4css1.css embed-stylesheet: no field-name-limit: 20
Individual configuration sections and settings are described in the following section.
Below are the Docutils runtime settings, listed by config file section. Any setting may be specified in any section, but only settings from active sections will be used. Sections correspond to Docutils components (module name or alias; section names are always in lowercase letters). Each Docutils application uses a specific set of components; corresponding configuration file sections are applied when the application is used. Configuration sections are applied in general-to-specific order, as follows:
[parsers], parser dependencies, and the section specific to the Parser used ("[... parser]"). Currently, only [restructuredtext parser] is applicable.
[readers], reader dependencies, and the section specific to the Reader used ("[... reader]"). For example, [pep reader] depends on [standalone reader].
[writers], writer dependencies, and the section specific to the Writer used ("[... writer]"). For example, [pep_html writer] depends on [html4css1 writer].
specific to the Application (front-end tool) in use ("[... application]").
Since any setting may be specified in any section, this ordering allows component- or application-specific overrides of earlier settings. For example, there may be Reader-specific overrides of general settings; Writer-specific overrides of Parser settings; Application-specific overrides of Writer settings; and so on.
If multiple configuration files are applicable, the process is completed (all sections are applied in the order given) for each one before going on to the next. For example, a "[pep_html writer] stylesheet" setting in an earlier configuration file would be overridden by an "[html4css1 writer] stylesheet" setting in a later file.
Some knowledge of Python is assumed for some attributes.
Settings in the "[general]" section are always applied.
Prefix prepended to all auto-generated IDs generated within the document, after id_prefix.
Default: "id". Options: --auto-id-prefix (hidden, intended mainly for programmatic use).
Include a time/datestamp in the document footer. Contains a format string for Python's time.strftime. See the time module documentation.
Default: None. Options: --date, -d, --time, -t, --no-datestamp.
Configuration file entry examples:
# Equivalent to --date command-line option, results in # ISO 8601 extended format datestamp, e.g. "2001-12-21": datestamp: %Y-%m-%d # Equivalent to --time command-line option, results in # date/timestamp like "2001-12-21 18:43 UTC": datestamp: %Y-%m-%d %H:%M UTC # Disables datestamp; equivalent to --no-datestamp: datestamp:
Report debug-level system messages.
Default: don't (None). Options: --debug, --no-debug.
At the end of processing, write all internal attributes of the document (document.__dict__) to stderr.
Default: don't (None). Options: --dump-internals (hidden, for development use only).
At the end of processing, write the pseudo-XML representation of the document to stderr.
Default: don't (None). Options: --dump-pseudo-xml (hidden, for development use only).
At the end of processing, write all Docutils settings to stderr.
Default: don't (None). Options: --dump-settings (hidden, for development use only).
At the end of processing, write a list of all transforms applied to the document to stderr.
Default: don't (None). Options: --dump-transforms (hidden, for development use only).
The text encoding for error output.
Default: "ascii". Options: --error-encoding, -e.
The error handler for unencodable characters in error output. See output_encoding_error_handler for acceptable values.
Default: "backslashreplace" for Python 2.3 and later; "replace" otherwise. Options: --error-encoding-error-handler, --error-encoding, -e.
A system message level threshold; non-halting system messages at or above this level will produce a non-zero exit status at normal exit. Exit status is the maximum system message level plus 10 (11 for INFO, etc.).
Default: disabled (5). Options: --exit-status.
List of internal attribues to expose as external attributes (with "internal:" namespace prefix). To specify multiple attributes in configuration files, use colons to separate names; on the command line, the option may be used more than once.
Default: don't (None). Options: --expose-internal-attribute (hidden, for development use only).
Enable or disable backlinks from footnotes and citations to their references.
Default: enabled (1). Options: --footnote-backlinks, --no-footnote-backlinks.
Include a "Generated by Docutils" credit and link in the document footer.
Default: off (None). Options: --generator, -g, --no-generator.
The threshold at or above which system messages are converted to exceptions, halting execution immediately. If traceback is set, the exception will propagate; otherwise, Docutils will exit.
Default: severe (4). Options: --halt, --strict.
Prefix prepended to all IDs generated within the document. See also auto_id_prefix.
Default: "" (empty). Options: --id-prefix (hidden, intended mainly for programmatic use).
The text encoding for input.
Default: auto-detect (None). Options: --input-encoding, -i.
The error handler for undecodable characters in the input. Acceptable values include:
Acceptable values are the same as for the "error" parameter of Python's unicode function; other values may be defined in applications or in future versions of Python.
Default: "strict". Options: --input-encoding-error-handler, --input-encoding, -i.
ISO 639 2-letter language code (3-letter codes used only if no 2-letter code exists).
Default: English ("en"). Options: --language, -l.
The text encoding for output.
Default: "UTF-8". Options: --output-encoding, -o.
The error handler for unencodable characters in the output. Acceptable values include:
Acceptable values are the same as for the "error" parameter of Python's encode string method; other values may be defined in applications or in future versions of Python.
Default: "strict". Options: --output-encoding-error-handler, --output-encoding, -o.
Path to a file where Docutils will write a list of files that the input and output depend on [3], e.g. due to file inclusion. [1] The format is one filename per line. This option is particularly useful in conjunction with programs like make.
Set to - in order to write dependencies to stdout.
Default: None. Option: --record-dependencies.
Verbosity threshold at or above which system messages are reported.
Default: warning (2). Options: --report, -r, --verbose, -v, --quiet, -q.
Enable or disable automatic section numbering by Docutils (docutils.transforms.parts.SectNum) associated with the sectnum directive.
If disabled, section numbers might be added to the output by the renderer (e.g. LaTeX or via a CSS style definition).
Default: enabled (1). Options: --section-numbering, --no-section-numbering.
Include a "View document source" link in the document footer. URL will be relative to the destination.
Default: don't (None). Options: --source-link, -s, --no-source-link.
An explicit URL for a "View document source" link, used verbatim.
Default: compute if source_link (None). Options: --source-url, --no-source-link.
When processing a document tree with the Visitor pattern, raise an error if a writer does not support a node type listed as optional. For transitional development use.
Default: disabled (None). Option: --strict-visitor (hidden, for development use only).
List of "classes" attribute values to remove from all elements in the document tree.
Warning
Potentially dangerous; use with caution.
Default: disabled (None). Option: --strip-class.
Enable the removal of comment elements from the document tree.
Default: disabled (None). Options: --strip-comments, --leave-comments.
List of "classes" attribute values; matching elements to be removed from the document tree.
Warning
Potentially dangerous; use with caution.
Default: disabled (None). Option: --strip-element-with-class.
The document title as metadata, which does not become part of the document body. It overrides a document-supplied title. For example, in HTML output the metadata document title appears in the title bar of the browser window.
Default: none. Option: --title.
Enable backlinks from section titles to table of contents entries ("entry"), to the top of the TOC ("top"), or disable ("none").
Default: "entry". Options: --toc-entry-backlinks, --toc-top-backlinks, --no-toc-backlinks.
Enable Python tracebacks when halt-level system messages and other exceptions occur. Useful for debugging, and essential for issue reports. Exceptions are allowed to propagate, instead of being caught and reported (in a user-friendly way) by Docutils.
Default: disabled (None) unless Docutils is run programmatically using the Publisher Interface. Options: --traceback, --no-traceback.
Path to a file for the output of system messages (warnings) [1].
Default: stderr (None). Options: --warnings.
Docutils currently supports only one parser, for reStructuredText.
Enable or disable directives that insert the contents of external files, such as the "include" & "raw". A "warning" system message (including the directive text) is inserted instead. (See also raw_enabled for another security-relevant setting.)
Default: enabled (1). Options: --file-insertion-enabled, --no-file-insertion.
Recognize and link to standalone PEP references (like "PEP 258").
Default: disabled (None); enabled (1) in PEP Reader. Options: --pep-references.
Base URL for PEP references.
Default: "http://www.python.org/peps/". Option: --pep-base-url.
Template for PEP file part of URL, interpolated with the PEP number and appended to pep_base_url.
Default: "pep-%04d". Option: --pep-file-url.
Enable or disable the "raw" directive. A "warning" system message (including the directive text) is inserted instead. (See also file_insertion_enabled for another security-relevant setting.)
Default: enabled (1). Options: --raw-enabled, --no-raw.
Recognize and link to standalone RFC references (like "RFC 822").
Default: disabled (None); enabled (1) in PEP Reader. Options: --rfc-references.
Base URL for RFC references.
Default: "http://www.faqs.org/rfcs/". Option: --rfc-base-url.
Number of spaces for hard tab expansion.
Default: 8. Options: --tab-width.
Remove spaces before footnote references.
Default: don't (None); may be overriden by a writer-specific footnote_references default though. Options: --trim-footnote-reference-space, --leave-footnote-reference-space.
Enable or disable the bibliographic field list transform (docutils.transforms.frontmatter.DocInfo).
Default: enabled (1). Options: --no-doc-info.
Enable or disable the promotion of a lone top-level section title to document title (and subsequent section title to document subtitle promotion; docutils.transforms.frontmatter.DocTitle).
Default: enabled (1). Options: --no-doc-title.
sectsubtitle_xform
Enable or disable the promotion of the title of a lone subsection to a subtitle (docutils.transforms.frontmatter.SectSubTitle).
Default: disabled (0). Options: --section-subtitles, --no-section-subtitles.
The pep_references and rfc_references settings ([restructuredtext parser]) are set on by default.
Under construction.
Generate XML with a DOCTYPE declaration.
Default: do (1). Options: --no-doctype.
Generate XML with indents and newlines.
Default: don't (None). Options: --indents.
Generate XML with newlines before and after tags.
Default: don't (None). Options: --newlines.
Generate XML with an XML declaration. Also defined for the HTML Writer.
Caution!
The XML declaration carries text encoding information, without which standard tools may be unable to read the generated XML.
Default: do (1). Options: --no-xml-declaration.
Format for block quote attributions: one of "dash" (em-dash prefix), "parentheses"/"parens", or "none". Also defined for the LaTeX Writer.
Default: "dash". Options: --attribution.
Scramble email addresses to confuse harvesters. In the reference URI, the "@" will be replaced by %-escapes (as of RFC 1738). In the visible text (link text) of an email reference, the "@" and all periods (".") will be surrounded by <span> tags. Furthermore, HTML entities are used to encode these characters in order to further complicate decoding the email address. For example, "abc@example.org" will be output as:
<a class="reference" href="mailto:abc%40example.org"> abc<span>@</span>example<span>.</span>org</a>
Note
While cloaking email addresses will have little to no impact on the rendering and usability of email links in most browsers, some browsers (e.g. the links browser) may decode cloaked email addresses incorrectly.
Default: don't cloak (None). Option: --cloak-email-addresses.
Remove extra vertical whitespace between items of bullet lists and enumerated lists, when list items are all "simple" (i.e., items each contain one paragraph and/or one "simple" sublist only). The behaviour can be specified directly via "class" attributes (values "compact" and "open") in the document.
Default: enabled (1). Options: --compact-lists, --no-compact-lists.
Remove extra vertical whitespace between items of field lists that are "simple" (i.e., all field bodies each contain at most one paragraph). The behaviour can be specified directly via "class" attributes (values "compact" and "open") in the document.
Default: enabled (1). Options: --compact-field-lists, --no-compact-field-lists.
Embed the stylesheet in the output HTML file. The stylesheet file must specified by the stylesheet_path setting and must be accessible during processing. Also defined for the LaTeX Writer.
Default: enabled. Options: --embed-stylesheet, --link-stylesheet.
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. 0 indicates "no limit". See also option_limit.
Default: 14 characters. Option: --field-name-limit.
Format for footnote references, one of "superscript" or "brackets". Also defined for the LaTeX Writer.
Overrides [2] trim_footnote_reference_space, if applicable. [4]
Default: "brackets". Option: --footnote-references.
The initial level for header elements. This does not affect the document title & subtitle; see doctitle_xform.
Default: 1 (for "<h1>"). Option: --initial-header-level.
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. 0 indicates "no limit". See also field_name_limit.
Default: 14 characters. Option: --option-limit.
A comma-separated list of CSS stylesheet URLs, used verbatim. Also defined for the LaTeX Writer.
Overrides also stylesheet-path. [2]
Default: None. Options: --stylesheet.
A comma-separated list of paths [1] to CSS stylesheets. If embed_stylesheet is False, paths are rewritten relative to the output HTML file. Also defined for the LaTeX Writer.
Also overrides "stylesheet". [2] Pass an empty string (to either "stylesheet" or "stylesheet_path") to deactivate stylesheet inclusion.
Default: "html4css1.css" in the docutils/writers/html4css1/ directory (installed automatically; for the exact machine-specific path, use the --help option). Options: --stylesheet-path.
Path to template file, which must be encoded in UTF-8 [1]. Also defined for the LaTeX Writer.
Default: "template.txt" in the docutils/writers/html4css1/ directory (installed automatically; for the exact machine-specific path, use the --help option). Options: --template.
Generate XML with an XML declaration. Also defined for the Docutils XML Writer.
Caution!
The XML declaration carries text encoding information, without which standard tools may be unable to read the generated XML.
Default: do (1). Options: --no-xml-declaration.
The PEP/HTML Writer derives from the standard HTML Writer, and shares all settings defined in the [html4css1 writer] section. The "[html4css1 writer]" section of configuration files is processed before the "[pep_html writer]" section.
Do not use a random banner image. Mainly used to get predictable results when testing.
Default: random enabled (None). Options: --no-random (hidden).
Home URL prefix for PEPs.
Default: current directory ("."). Options: --pep-home.
Python's home URL.
Default: parent directory (".."). Options: --python-home.
The PEP/HTML Writer's default for the following settings differ from those of the standard HTML Writer:
The S5/HTML Writer derives from the standard HTML Writer, and shares all settings defined in the [html4css1 writer] section. The "[html4css1 writer]" section of configuration files is processed before the "[s5_html writer]" section.
Auto-hide the presentation controls in slideshow mode, or or keep them visible at all times.
Default: auto-hide (1). Options: --hidden-controls, --visible-controls.
Enable or disable the current slide indicator ("1/15").
Default: disabled (None). Options: --current-slide, --no-current-slide.
Allow or prevent the overwriting of existing theme files in the ui/<theme> directory. This has no effect if "theme_url" is used.
Default: keep existing theme files (None). Options: --keep-theme-files, --overwrite-theme-files.
Name of an installed S5 theme, to be copied into a ui/<theme> subdirectory, beside the destination file (output HTML). Note that existing theme files will not be overwritten; the existing theme directory must be deleted manually. Also overrides the "theme_url" setting. [2]
Default: "default". Option: --theme.
The URL of an S5 theme directory. The destination file (output HTML) will link to this theme; nothing will be copied. Also overrides the "theme" setting. [2]
Default: None. Option: --theme-url.
The initial view mode, either "slideshow" or "outline".
Default: "slidewhow". Option: --view-mode.
The S5/HTML Writer's default for the following settings differ from those of the standard HTML Writer:
To get pagenumbers in the table of contents the table of contents must be generated by LaTeX. Usually latex must be run twice to get numbers correct.
Default: on. Options: --use-latex-toc, --use-docutils-toc.
Attach author and date to the document title instead of the document info table.
Default: off. Options: --use-latex-docinfo, --use-docutils-docinfo
Use DUfootnote and DUfootnotetext for footnotes instead of the deprecated simulation with figure-floats.
Note this will change to use the footnote command and footnote numbering by LaTeX in the future.
Default: on. Options: --use-latex-footnotes, --figure-footnotes.
Use cite for citations instead of a simulation with figure-floats.
Default: off. Options: --use-latex-citations, --figure-citations.
Use LaTeX abstract environment for the document's abstract.
Default: off. Options: --use-latex-abstract, --topic-abstract.
Color of any hyperlinks embedded in text. Use "0" to disable coloring of links.
Default: "blue". Option: --hyperlink-color.
Specify latex documentclass, but beaware that books have chapters articles not.
Default: "article". Option: --documentclass.
Specify document options. Multiple options can be given, separated by commas.
Default: "10pt,a4paper". Option: --documentoptions.
Specify LaTeX font encoding. Multiple options can be given, separated by commas. Possible values are "", "T1", "OT1", "LGR,T1" or any other combination of options to the fontenc package.
Default: "T1". Option: --font-encoding.
Embed the stylesheet(s) in the header of the output file. The stylesheets must be accessible during processing. Also defined for the HTML Writer (with default on).
Default: off. Options: --embed-stylesheet, --link-stylesheet.
A comma-separated list of style files. Also defined for the HTML Writer.
Overrides also stylesheet_path. [2]
If embed_stylesheet is False (default), the stylesheet files are referenced with \usepackage (extension .sty or no extension) or \input (any other extension).
Default: no stylesheet (""). Option: --stylesheet.
Similar to stylesheet, however paths [1] are rewritten relative to the output file (if there is a common part in the given path and the output file path). Also defined for the HTML Writer.
Run latex from the directory containing the output file. Fails for files in the TEXINPUTS path; use stylesheet in this case.
Also overrides stylesheet. [2]
Default: no stylesheet (""). Option: --stylesheet-path.
Path to template file, which must be encoded in UTF-8 [1]. Also defined for the HTML Writer.
Default: "default.tex" in the docutils/writers/latex2e/ directory (installed automatically; for the exact machine-specific path, use the --help option). Options: --template.
Format for footnote references: one of "superscript" or "brackets". Also defined for the HTML Writer.
Overrides [2] trim_footnote_reference_space, if applicable [4].
Default: "superscript". Option: --footnote-references.
Format for block quote attributions, the same as for the html-writer: one of "dash" (em-dash prefix), "parentheses"/"parens" or "none". Also defined for the HTML Writer.
Default: "dash". Option: --attribution.
Enable or disable compound enumerators for nested enumerated lists (e.g. "1.2.a.ii").
Default: disabled (None). Options: --compound-enumerators, --no-compound-enumerators.
Enable or disable section ("." subsection ...) prefixes for compound enumerators. This has no effect unless compound_enumerators are enabled.
Default: disabled (None). Options: --section-prefix-for-enumerators, --no-section-prefix-for-enumerators.
The separator between section number prefix and enumerator for compound enumerated lists (see compound_enumerators).
Generally it isn't recommended to use both sub-sections and nested enumerated lists with compound enumerators. This setting avoids ambiguity in the situation where a section "1" has a list item enumerated "1.1", and subsection "1.1" has list item "1". With a separator of ".", these both would translate into a final compound enumerator of "1.1.1". With a separator of "-", we get the unambiguous "1-1.1" and "1.1-1".
Default: "-". Option: --section-enumerator-separator.
Specify the drawing of separation lines.
Default: "standard". Option: --table-style.
No settings are defined for this Writer.
List of wildcard (shell globing) patterns to silently ignore. To specify multiple patterns in configuration files, use colon-separated patterns; on the command line, the option may be used more than once.
Default: ['.svn', 'CVS']. Options: --ignore.
List of directories not to process. To specify multiple directories in configuration files, use colon-separated paths; on the command line, the option may be used more than once.
Default: none ([]). Options: --prune.
Recursively scan subdirectories, or ignore subdirectories.
Default: recurse (1). Options: --recurse, --local.
Work silently (no progress messages). Independent of "report_level".
Default: show progress (None). Options: --silent.
(To be completed.)
These settings are only effective as command-line options; setting them in configuration files has no effect.
Path to a configuration file to read (if it exists) [1]. Settings may override defaults and earlier settings. The config file is processed immediately. Multiple --config options may be specified; each will be processed in turn.
Filesystem path settings contained within the config file will be interpreted relative to the config file's location (not relative to the current working directory).
Default: None. Options: --config.
These settings are for internal use only; setting them in configuration files has no effect, and there are no corresponding command-line options.
List of paths of applied configuration files.
Default: None. No command-line options.
(buildhtml.py front end.) List of paths to source directories, set from positional arguments.
Default: current working directory (None). No command-line options.
Prevent standard configuration files from being read. For programmatic use only.
Default: config files enabled (None). No command-line options.
Path to output destination, set from positional arguments.
Default: stdout (None). No command-line options.
Path to input source, set from positional arguments.
Default: stdin (None). No command-line options.
| [1] | (1, 2, 3, 4, 5, 6, 7) Path relative to the working directory of the process at launch. |
| [2] | (1, 2, 3, 4, 5, 6, 7, 8) The overridden setting will automatically be set to None for command-line options and config file settings. Client programs which specify defaults that override other settings must do the overriding explicitly, by assigning None to the other settings. |
| [3] | Some notes on the dependency recorder:
|
| [4] | (1, 2) The footnote space is trimmed if the reference style is "superscript", and it is left if the reference style is "brackets". The overriding only happens if the parser supports the trim_footnote_reference_space option. |
Formerly, Docutils configuration files contained a single "[options]" section only. This was found to be inflexible, and in August 2003 Docutils adopted the current component-based configuration file sections as described above. Docutils will still recognize the old "[options]" section, but complains with a deprecation warning.
To convert existing config files, the easiest way is to change the section title: change "[options]" to "[general]". Most settings haven't changed. The only ones to watch out for are these:
| Old-Format Setting | New Section & Setting |
|---|---|
| pep_stylesheet | [pep_html writer] stylesheet |
| pep_stylesheet_path | [pep_html writer] stylesheet_path |
| pep_template | [pep_html writer] template |