Docutils Configuration Files

Author: David Goodger
Contact: goodger@python.org
Revision: 1.12
Date: 2004-04-28
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:

  1. /etc/docutils.conf: This is a system-wide configuration file, applicable to all Docutils processing on the system.
  2. ./docutils.conf: This is a project-specific configuration file, located in the current directory. The Docutils front end has to be executed from the directory containing this configuration file for it to take effect (note that this may have nothing to do with the location of the source files). Settings in the project-specific configuration file will override corresponding settings in the system-wide file.
  3. ~/.docutils: This is a user-specific configuration file, located in the user's home directory. Settings in this file will override corresponding settings in both the system-wide and project-specific configuration files.

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 File Syntax

Configuration files use the standard ConfigParser.py Python module. 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:

Configuration File Sections & Entries

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:

  1. [general]

  2. [parsers], parser dependencies, and the section specific to the Parser used ("[... parser]"). Currently, only [restructuredtext parser] is applicable.

  3. [readers], reader dependencies, and the section specific to the Reader used ("[... reader]"). For example, [pep reader] depends on [standalone reader].

  4. [writers], writer dependencies, and the section specific to the Writer used ("[... writer]"). For example, [pep_html writer] depends on [html4css1 writer].

  5. [applications], application dependencies, and the section

    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.

[general]

Settings in the "[general]" section are always applied.

datestamp

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:
debug

Report debug-level system messages.

Default: don't (None). Options: --debug, --no-debug.

dump_internals

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).

dump_pseudo_xml

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).

dump_settings

At the end of processing, write all Docutils settings to stderr.

Default: don't (None). Options: --dump-settings (hidden, for development use only).

dump_transforms

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).

error_encoding

The text encoding for error output.

Default: "ascii". Options: --error-encoding, -e.

error_encoding_error_handler

The encoding error handler for unencodable characters in error output. Acceptable values are the same as for the "error" parameter of Python's encode string method.

Default: "backslashreplace" for Python 2.3 and later; "replace" otherwise. Options: --error-encoding-error-handler, --error-encoding, -e.

exit_level

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.

expose_internals

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).

footnote_backlinks

Enable or disable backlinks from footnotes and citations to their references.

Default: enabled (1). Options: --footnote-backlinks, --no-footnote-backlinks.

generator

Include a "Generated by Docutils" credit and link in the document footer.

Default: off (None). Options: --generator, -g, --no-generator.

halt_level

The threshold at or above which system messages are converted to exceptions, halting execution immediately.

Default: severe (4). Options: --halt, --strict.

input_encoding

The text encoding for input.

Default: auto-detect (None). Options: --input-encoding, -i.

language_code

ISO 639 2-letter language code (3-letter codes used only if no 2-letter code exists).

Default: English ("en"). Options: --language, -l.

output_encoding

The text encoding for output.

Default: "UTF-8". Options: --output-encoding, -o.

output_encoding_error_handler

The encoding error handler for unencodable characters in output. Acceptable values are the same as for the "error" parameter of Python's encode string method.

Default: "strict". Options: --output-encoding-error-handler, --output-encoding, -o.

report_level

Verbosity threshold at or above which system messages are reported.

Default: warning (2). Options: --report, -r, --verbose, -v, --quiet, -q.

sectnum_xform

Enable or disable the section numbering transform (docutils.transforms.parts.SectNum).

Default: enabled (1). Options: --no-section-numbering.

source_link

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.

source_url

An explicit URL for a "View document source" link, used verbatim.

Default: compute if source_link (None). Options: --source-url, --no-source-link.

toc_backlinks

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.

traceback

Enable Python tracebacks when an error occurs.

Default: disabled (None). Options: --traceback, --no-traceback.

warning_stream

Path to a file for the output of system messages (warnings) 1.

Default: stderr (None). Options: --warnings.

[parsers]

Docutils currently supports only one parser, for reStructuredText.

[restructuredtext parser]

pep_references

Recognize and link to PEP references (like "PEP 258").

Default: disabled (None); enabled (1) in PEP Reader. Options: --pep-references.

rfc_references

Recognize and link to RFC references (like "RFC 822").

Default: disabled (None); enabled (1) in PEP Reader. Options: --rfc-references.

tab_width

Number of spaces for hard tab expansion.

Default: 8. Options: --tab-width.

trim-footnote-reference-space

Remove spaces before footnote references.

Default: don't (None). Options: --trim-footnote-reference-space.

[readers]

[standalone reader]

docinfo_xform

Enable or disable the bibliographic field list transform (docutils.transforms.frontmatter.DocInfo).

Default: enabled (1). Options: --no-doc-info.

doctitle_xform

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.

[pep reader]

The pep_references and rfc_references options ([restructuredtext parser]) are set on by default.

[python reader]

Under construction.

[writers]

[docutils_xml writer]

doctype_declaration

Generate XML with a DOCTYPE declaration.

Default: do (1). Options: --no-doctype.

indents

Generate XML with indents and newlines.

Default: don't (None). Options: --indents.

newlines

Generate XML with newlines before and after tags.

Default: don't (None). Options: --newlines.

xml_declaration

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.

[html4css1 writer]

attribution

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.

compact_lists

Remove extra vertical whitespace between items of bullet lists and enumerated lists, when list items are "simple" (i.e., all items each contain one paragraph and/or one "simple" sublist only).

Default: enabled (1). Options: --compact-lists, --no-compact-lists.

embed_stylesheet

Embed the stylesheet in the output HTML file. The stylesheet file must be accessible during processing. The stylesheet is embedded inside a comment, so it must not contain the text "--" (two hyphens).

Default: link, don't embed (None). Options: --embed-stylesheet, --link-stylesheet.

footnote_references

Format for footnote references, one of "superscript" or "brackets". Also defined for the LaTeX Writer.

Default: "superscript"; "brackets" in PEP/HTML Writer. Options: --footnote-references.

initial_header_level

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.

stylesheet

CSS stylesheet URL, used verbatim. Overridden by "stylesheet_path" URL option (--stylesheet-path). Also defined for the LaTeX Writer.

Default: "default.css". Options: --stylesheet.

stylesheet_path

Path to CSS stylesheet 1. Overrides "stylesheet" URL option (--stylesheet). Path is adjusted relative to the output HTML file. Also defined for the LaTeX Writer.

Default: None. Options: --stylesheet-path.

xml_declaration

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.

[pep_html writer]

The PEP/HTML Writer derives from the standard HTML Writer, and shares all settings defined in the [html4css1 writer] section. The "[html4css1 writer]" section is processed before "[pep_html writer]".

no_random

Workaround for platforms which core-dump on "import random".

Default: random enabled (None). Options: --no-random (hidden).

pep_home

Home URL prefix for PEPs.

Default: current directory ("."). Options: --pep-home.

template

Path to PEP template file 1.

Default: "pep-html-template" (in current directory). Options: --template.

python_home

Python's home URL.

Default: parent directory (".."). Options: --python-home.

[latex2e writer]

use_latex_toc

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.

Note: LaTeX will number the sections, which might be a bug in this case.

Default: off. Option: --use-latex-toc.

use_latex_footnotes

Use LaTeX-footnotes not a figure simulation. This might give no Hyperrefs on /to footnotes, but should be able to handle an unlimited number of footnotes.

Default: off. Option: --use-latex-footnotes.

hyperlink_color

Color of any hyperlinks embedded in text. Use "0" to disable coloring of links.

Default: "blue", use "0" to disable. Option: --hyperlink-color.

documentclass

Specify latex documentclass, but beaware that books have chapters articles not.

Default: "article". Option: --documentclass.

documentoptions

Specify document options. Multiple options can be given, separated by commas.

Default is "10pt". Option: --documentoptions.

stylesheet

Specify a stylesheet file. The file will be input by latex in the document header. If this is set to "" disables generation of input latex command. Also defined for the HTML Writer.

Default: no stylesheet (""). Option: --stylesheet.

stylesheet_path

Path to stylesheet 1. Overrides "stylesheet" setting (--stylesheet). XXX LaTeX semantics? Also defined for the HTML Writer.

Default: None. Option: --stylesheet-path.

footnote_references

Format for footnote references: one of "superscript" or "brackets". Also defined for the HTML Writer.

Default is "brackets". Option: --footnote-references.

attribution

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.

compound_enumerators

Enable or disable compound enumerators for nested enumerated lists (e.g. "1.2.a.ii").

Default: disabled (None). Options: --compound-enumerators, --no-compound-enumerators.

section_prefix_for_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.

section_enumerator_separator

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.

[pseudoxml writer]

No settings are defined for this Writer.

[applications]

[buildhtml application]

prune

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.

recurse

Recursively scan subdirectories, or ignore subdirectories.

Default: recurse (1). Options: --recurse, --local.

silent

Work silently (no progress messages). Independent of "report_level".

Default: show progress (None). Options: --silent.

[docfactory application]

(To be completed.)

Other Settings

These settings are only effective as command-line options, positional arguments, or for internal use; setting them in configuration files has no effect.

config

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.

_directories

(buildhtml.py front end.) List of paths to source directories, set from positional arguments.

Default: current working directory (None). No command-line options.

_disable_config

Prevent standard configuration files from being read. For internal use only.

Default: config files enabled (None). No command-line options.

_destination

Path to output destination, set from positional arguments.

Default: stdout (None). No command-line options.

_source

Path to input source, set from positional arguments.

Default: stdin (None). No command-line options.

[1](1, 2, 3, 4, 5) Path relative to the working directory of the process at launch.

Old-Format Configuration Files

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