1
==============================
2
Docutils Configuration Files
3
==============================
6
:Contact: goodger@python.org
7
:Revision: $Revision: 1.12 $
8
:Date: $Date: 2004/04/28 21:49:53 $
9
:Copyright: This document has been placed in the public domain.
13
.. Cross-reference command-line options with configuration file
14
settings? Make alphabetical indexes of both.
16
Configuration files are used for persistent customization; they can be
17
set once and take effect every time you use a front-end tool.
18
Configuration file settings override the built-in defaults, and
19
command-line options override all.
21
By default, Docutils checks the following places for configuration
22
files, in the following order:
24
1. ``/etc/docutils.conf``: This is a system-wide configuration file,
25
applicable to all Docutils processing on the system.
27
2. ``./docutils.conf``: This is a project-specific configuration file,
28
located in the current directory. The Docutils front end has to be
29
executed from the directory containing this configuration file for
30
it to take effect (note that this may have nothing to do with the
31
location of the source files). Settings in the project-specific
32
configuration file will override corresponding settings in the
35
3. ``~/.docutils``: This is a user-specific configuration file,
36
located in the user's home directory. Settings in this file will
37
override corresponding settings in both the system-wide and
38
project-specific configuration files.
40
If more than one configuration file is found, all will be read but
41
later entries will override earlier ones. For example, a "stylesheet"
42
entry in a user-specific configuration file will override a
43
"stylesheet" entry in the system-wide file.
45
The default implicit config file paths can be overridden by the
46
``DOCUTILSCONFIG`` environment variable. ``DOCUTILSCONFIG`` should
47
contain a colon-separated (semicolon-separated on Windows) sequence of
48
config file paths to search for; leave it empty to disable implicit
49
config files altogether. Tilde-expansion is performed on paths.
50
Paths are interpreted relative to the current working directory.
51
Empty path items are ignored.
53
In addition, a configuration file may be explicitly specified with the
54
"--config" command-line option. This configuration file is read after
55
the three implicit ones listed above (or the ones defined by the
56
``DOCUTILSCONFIG`` environment variable), and its entries will have
60
-------------------------
61
Configuration File Syntax
62
-------------------------
64
Configuration files use the standard ConfigParser.py_ Python_ module.
65
From its documentation:
67
The configuration file consists of sections, lead by a "[section]"
68
header and followed by "name: value" entries, with continuations
69
in the style of `RFC 822`_; "name=value" is also accepted. Note
70
that leading whitespace is removed from values. ... Lines
71
beginning with "#" or ";" are ignored and may be used to provide
74
.. Note:: No format string interpolation is done.
76
Configuration file entry names correspond to internal runtime
77
settings. Underscores ("_") and hyphens ("-") can be used
78
interchangably in entry names; hyphens are automatically converted to
81
For on/off switch settings (booleans), the following values are
84
* On: "true", "yes", "on", "1"
85
* Off: "false", "no", "off", "0", "" (no value)
88
-------------------------------------
89
Configuration File Sections & Entries
90
-------------------------------------
92
Below are the Docutils runtime settings, listed by config file
93
section. Any setting may be specified in any section, but only
94
settings from active sections will be used. Sections correspond to
95
Docutils components (module name or alias; section names are always in
96
lowercase letters). Each `Docutils application`_ uses a specific set
97
of components; corresponding configuration file sections are applied
98
when the application is used. Configuration sections are applied in
99
general-to-specific order, as follows:
103
2. `[parsers]`_, parser dependencies, and the section specific to the
104
Parser used ("[... parser]"). Currently, only `[restructuredtext
105
parser]`_ is applicable.
107
3. `[readers]`_, reader dependencies, and the section specific to the
108
Reader used ("[... reader]"). For example, `[pep reader]`_ depends
109
on `[standalone reader]`_.
111
4. `[writers]`_, writer dependencies, and the section specific to the
112
Writer used ("[... writer]"). For example, `[pep_html writer]`_
113
depends on `[html4css1 writer]`_.
115
5. `[applications]`_, application dependencies, and the section
116
specific to the Application (front-end tool) in use
117
("[... application]").
119
Since any setting may be specified in any section, this ordering
120
allows component- or application-specific overrides of earlier
121
settings. For example, there may be Reader-specific overrides of
122
general settings; Writer-specific overrides of Parser settings;
123
Application-specific overrides of Writer settings; and so on.
125
If multiple configuration files are applicable, the process is
126
completed (all sections are applied in the order given) for each one
127
before going on to the next. For example, a "[pep_html writer]
128
stylesheet" setting in an earlier configuration file would be
129
overridden by an "[html4css1 writer] stylesheet" setting in a later
132
Some knowledge of Python_ is assumed for some attributes.
135
http://www.python.org/doc/current/lib/module-ConfigParser.html
136
.. _Python: http://www.python.org/
137
.. _RFC 822: http://www.rfc-editor.org/rfc/rfc822.txt
138
.. _Docutils application: tools.html
144
Settings in the "[general]" section are always applied.
147
Include a time/datestamp in the document footer. Contains a
148
format string for Python's ``time.strftime``. See the `time
149
module documentation`__.
151
Default: None. Options: ``--date, -d, --time, -t,
154
Configuration file entry examples::
156
# Equivalent to --date command-line option, results in
157
# ISO 8601 extended format datestamp, e.g. "2001-12-21":
160
# Equivalent to --time command-line option, results in
161
# date/timestamp like "2001-12-21 18:43 UTC":
162
datestamp: %Y-%m-%d %H:%M UTC
164
# Disables datestamp; equivalent to --no-datestamp:
167
__ http://www.python.org/doc/current/lib/module-time.html
170
Report debug-level system messages.
172
Default: don't (None). Options: ``--debug, --no-debug``.
175
At the end of processing, write all internal attributes of the
176
document (``document.__dict__``) to stderr.
178
Default: don't (None). Options: ``--dump-internals`` (hidden, for
179
development use only).
182
At the end of processing, write the pseudo-XML representation of
183
the document to stderr.
185
Default: don't (None). Options: ``--dump-pseudo-xml`` (hidden,
186
for development use only).
189
At the end of processing, write all Docutils settings to stderr.
191
Default: don't (None). Options: ``--dump-settings`` (hidden, for
192
development use only).
195
At the end of processing, write a list of all transforms applied
196
to the document to stderr.
198
Default: don't (None). Options: ``--dump-transforms`` (hidden,
199
for development use only).
202
The text encoding for error output.
204
Default: "ascii". Options: ``--error-encoding, -e``.
206
_`error_encoding_error_handler`
207
The encoding error handler for unencodable characters in error
208
output. Acceptable values are the same as for the "error"
209
parameter of Python's ``encode`` string method.
211
Default: "backslashreplace" for Python 2.3 and later; "replace"
212
otherwise. Options: ``--error-encoding-error-handler,
213
--error-encoding, -e``.
216
A system message level threshold; non-halting system messages at
217
or above this level will produce a non-zero exit status at normal
218
exit. Exit status is the maximum system message level plus 10 (11
221
Default: disabled (5). Options: ``--exit``.
224
List of internal attribues to expose as external attributes (with
225
"internal:" namespace prefix). To specify multiple attributes in
226
configuration files, use colons to separate names; on the command
227
line, the option may be used more than once.
229
Default: don't (None). Options: ``--expose-internal-attribute``
230
(hidden, for development use only).
232
_`footnote_backlinks`
233
Enable or disable backlinks from footnotes and citations to their
236
Default: enabled (1). Options: ``--footnote-backlinks,
237
--no-footnote-backlinks``.
240
Include a "Generated by Docutils" credit and link in the document
243
Default: off (None). Options: ``--generator, -g,
247
The threshold at or above which system messages are converted to
248
exceptions, halting execution immediately.
250
Default: severe (4). Options: ``--halt, --strict``.
253
The text encoding for input.
255
Default: auto-detect (None). Options: ``--input-encoding, -i``.
258
`ISO 639`_ 2-letter language code (3-letter codes used only if no
259
2-letter code exists).
261
Default: English ("en"). Options: ``--language, -l``.
264
The text encoding for output.
266
Default: "UTF-8". Options: ``--output-encoding, -o``.
268
_`output_encoding_error_handler`
269
The encoding error handler for unencodable characters in output.
270
Acceptable values are the same as for the "error" parameter of
271
Python's ``encode`` string method.
273
Default: "strict". Options: ``--output-encoding-error-handler,
274
--output-encoding, -o``.
277
Verbosity threshold at or above which system messages are
280
Default: warning (2). Options: ``--report, -r, --verbose, -v,
284
Enable or disable the section numbering transform
285
(docutils.transforms.parts.SectNum).
287
Default: enabled (1). Options: ``--no-section-numbering``.
290
Include a "View document source" link in the document footer. URL
291
will be relative to the destination.
293
Default: don't (None). Options: ``--source-link, -s,
297
An explicit URL for a "View document source" link, used verbatim.
299
Default: compute if source_link (None). Options: ``--source-url,
303
Enable backlinks from section titles to table of contents entries
304
("entry"), to the top of the TOC ("top"), or disable ("none").
306
Default: "entry". Options: ``--toc-entry-backlinks,
307
--toc-top-backlinks, --no-toc-backlinks``.
310
Enable Python tracebacks when an error occurs.
312
Default: disabled (None). Options: ``--traceback,
316
Path to a file for the output of system messages (warnings)
319
Default: stderr (None). Options: ``--warnings``.
325
Docutils currently supports only one parser, for reStructuredText.
328
[restructuredtext parser]
329
`````````````````````````
332
Recognize and link to PEP references (like "PEP 258").
334
Default: disabled (None); enabled (1) in PEP Reader. Options:
335
``--pep-references``.
338
Recognize and link to RFC references (like "RFC 822").
340
Default: disabled (None); enabled (1) in PEP Reader. Options:
341
``--rfc-references``.
344
Number of spaces for hard tab expansion.
346
Default: 8. Options: ``--tab-width``.
348
_`trim-footnote-reference-space`
349
Remove spaces before footnote references.
351
Default: don't (None). Options:
352
``--trim-footnote-reference-space``.
363
Enable or disable the bibliographic field list transform
364
(docutils.transforms.frontmatter.DocInfo).
366
Default: enabled (1). Options: ``--no-doc-info``.
369
Enable or disable the promotion of a lone top-level section title
370
to document title (and subsequent section title to document
371
subtitle promotion; docutils.transforms.frontmatter.DocTitle).
373
Default: enabled (1). Options: ``--no-doc-title``.
379
The `pep_references`_ and `rfc_references`_ options
380
(`[restructuredtext parser]`_) are set on by default.
392
[docutils_xml writer]
393
`````````````````````
395
_`doctype_declaration`
396
Generate XML with a DOCTYPE declaration.
398
Default: do (1). Options: ``--no-doctype``.
401
Generate XML with indents and newlines.
403
Default: don't (None). Options: ``--indents``.
406
Generate XML with newlines before and after tags.
408
Default: don't (None). Options: ``--newlines``.
410
.. _xml_declaration [docutils_xml writer]:
413
Generate XML with an XML declaration. Also defined for the
416
.. Caution:: The XML declaration carries text encoding
417
information, without which standard tools may be unable to read
420
Default: do (1). Options: ``--no-xml-declaration``.
422
__ `xml_declaration [html4css1 writer]`_
428
.. _attribution [html4css1 writer]:
431
Format for block quote attributions: one of "dash" (em-dash
432
prefix), "parentheses"/"parens", or "none". Also defined for the
435
Default: "dash". Options: ``--attribution``.
437
__ `attribution [latex2e writer]`_
440
Remove extra vertical whitespace between items of bullet lists and
441
enumerated lists, when list items are "simple" (i.e., all items
442
each contain one paragraph and/or one "simple" sublist only).
444
Default: enabled (1). Options: ``--compact-lists,
445
--no-compact-lists``.
448
Embed the stylesheet in the output HTML file. The stylesheet file
449
must be accessible during processing. The stylesheet is embedded
450
inside a comment, so it must not contain the text "``--``" (two
453
Default: link, don't embed (None). Options: ``--embed-stylesheet,
456
.. _footnote_references [html4css1 writer]:
459
Format for footnote references, one of "superscript" or
460
"brackets". Also defined for the `LaTeX Writer`__.
462
Default: "superscript"; "brackets" in PEP/HTML Writer. Options:
463
``--footnote-references``.
465
__ `footnote_references [latex2e writer]`_
467
_`initial_header_level`
468
The initial level for header elements. This does not affect the
469
document title & subtitle; see doctitle_xform_.
471
Default: 1 (for "<h1>"). Option: ``--initial-header-level``.
473
.. _stylesheet [html4css1 writer]:
476
CSS stylesheet URL, used verbatim. Overridden by
477
"stylesheet_path" URL option (``--stylesheet-path``). Also
478
defined for the `LaTeX Writer`__.
480
Default: "default.css". Options: ``--stylesheet``.
482
__ `stylesheet [latex2e writer]`_
484
.. _stylesheet_path [html4css1 writer]:
487
Path to CSS stylesheet [#pwd]_. Overrides "stylesheet" URL option
488
(``--stylesheet``). Path is adjusted relative to the output HTML
489
file. Also defined for the `LaTeX Writer`__.
491
Default: None. Options: ``--stylesheet-path``.
493
__ `stylesheet_path [latex2e writer]`_
495
.. _xml_declaration [html4css1 writer]:
498
Generate XML with an XML declaration. Also defined for the
499
`Docutils XML Writer`__.
501
.. Caution:: The XML declaration carries text encoding
502
information, without which standard tools may be unable to read
505
Default: do (1). Options: ``--no-xml-declaration``.
507
__ `xml_declaration [docutils_xml writer]`_
513
The PEP/HTML Writer derives from the standard HTML Writer, and shares
514
all settings defined in the `[html4css1 writer]`_ section. The
515
"[html4css1 writer]" section is processed before "[pep_html writer]".
518
Workaround for platforms which core-dump on "``import random``".
520
Default: random enabled (None). Options: ``--no-random``
524
Home URL prefix for PEPs.
526
Default: current directory ("."). Options: ``--pep-home``.
529
Path to PEP template file [#pwd]_.
531
Default: "pep-html-template" (in current directory). Options:
537
Default: parent directory (".."). Options: ``--python-home``.
544
To get pagenumbers in the table of contents the table of contents
545
must be generated by latex. Usually latex must be run twice to get
548
*Note:* LaTeX will number the sections, which might be a bug in
551
Default: off. Option: ``--use-latex-toc``.
553
.. XXX Missing: use_latex_docinfo
555
_`use_latex_footnotes`
556
Use LaTeX-footnotes not a figure simulation. This might give no
557
Hyperrefs on /to footnotes, but should be able to handle an
558
unlimited number of footnotes.
560
Default: off. Option: ``--use-latex-footnotes``.
563
Color of any hyperlinks embedded in text. Use "0" to disable
566
Default: "blue", use "0" to disable. Option:
567
``--hyperlink-color``.
570
Specify latex documentclass, *but* beaware that books have chapters
573
Default: "article". Option: ``--documentclass``.
576
Specify document options. Multiple options can be given, separated by
579
Default is "10pt". Option: ``--documentoptions``.
581
.. _stylesheet [latex2e writer]:
584
Specify a stylesheet file. The file will be ``input`` by latex in
585
the document header. If this is set to "" disables generation of
586
input latex command. Also defined for the `HTML Writer`__.
588
Default: no stylesheet (""). Option: ``--stylesheet``.
590
__ `stylesheet [html4css1 writer]`_
592
.. _stylesheet_path [latex2e writer]:
595
Path to stylesheet [#pwd]_. Overrides "stylesheet" setting
596
(``--stylesheet``). XXX LaTeX semantics? Also defined for the
599
Default: None. Option: ``--stylesheet-path``.
601
__ `stylesheet_path [html4css1 writer]`_
603
.. XXX Missing: embed_stylesheet
605
.. _footnote_references [latex2e writer]:
608
Format for footnote references: one of "superscript" or
609
"brackets". Also defined for the `HTML Writer`__.
611
Default is "brackets". Option: ``--footnote-references``.
613
__ `footnote_references [html4css1 writer]`_
615
.. _attribution [latex2e writer]:
618
Format for block quote attributions, the same as for the
619
html-writer: one of "dash" (em-dash prefix),
620
"parentheses"/"parens" or "none". Also defined for the `HTML
623
Default: "dash". Option: ``--attribution``.
625
__ `attribution [html4css1 writer]`_
627
_`compound_enumerators`
628
Enable or disable compound enumerators for nested enumerated lists
631
Default: disabled (None). Options: ``--compound-enumerators``,
632
``--no-compound-enumerators``.
634
_`section_prefix_for_enumerators`
635
Enable or disable section ("." subsection ...) prefixes for
636
compound enumerators. This has no effect unless
637
`compound_enumerators`_ are enabled.
639
Default: disabled (None). Options:
640
``--section-prefix-for-enumerators``,
641
``--no-section-prefix-for-enumerators``.
643
_`section_enumerator_separator`
644
The separator between section number prefix and enumerator for
645
compound enumerated lists (see `compound_enumerators`_).
647
Generally it isn't recommended to use both sub-sections and nested
648
enumerated lists with compound enumerators. This setting avoids
649
ambiguity in the situation where a section "1" has a list item
650
enumerated "1.1", and subsection "1.1" has list item "1". With a
651
separator of ".", these both would translate into a final compound
652
enumerator of "1.1.1". With a separator of "-", we get the
653
unambiguous "1-1.1" and "1.1-1".
655
Default: "-". Option: ``--section-enumerator-separator``.
661
No settings are defined for this Writer.
667
[buildhtml application]
668
```````````````````````
671
List of directories not to process. To specify multiple
672
directories in configuration files, use colon-separated paths; on
673
the command line, the option may be used more than once.
675
Default: none ([]). Options: ``--prune``.
678
Recursively scan subdirectories, or ignore subdirectories.
680
Default: recurse (1). Options: ``--recurse, --local``.
683
Work silently (no progress messages). Independent of
686
Default: show progress (None). Options: ``--silent``.
689
[docfactory application]
690
````````````````````````
698
These settings are only effective as command-line options, positional
699
arguments, or for internal use; setting them in configuration files
703
Path to a configuration file to read (if it exists) [#pwd]_.
704
Settings may override defaults and earlier settings. The config
705
file is processed immediately. Multiple ``--config`` options may
706
be specified; each will be processed in turn.
708
Filesystem path settings contained within the config file will be
709
interpreted relative to the config file's location (*not* relative
710
to the current working directory).
712
Default: None. Options: ``--config``.
715
(``buildhtml.py`` front end.) List of paths to source
716
directories, set from positional arguments.
718
Default: current working directory (None). No command-line
722
Prevent standard configuration files from being read. For
725
Default: config files enabled (None). No command-line options.
728
Path to output destination, set from positional arguments.
730
Default: stdout (None). No command-line options.
733
Path to input source, set from positional arguments.
735
Default: stdin (None). No command-line options.
738
.. _ISO 639: http://lcweb.loc.gov/standards/iso639-2/englangn.html
740
.. [#pwd] Path relative to the working directory of the process at
744
------------------------------
745
Old-Format Configuration Files
746
------------------------------
748
Formerly, Docutils configuration files contained a single "[options]"
749
section only. This was found to be inflexible, and in August 2003
750
Docutils adopted the current component-based configuration file
751
sections as described above. Docutils will still recognize the old
752
"[options]" section, but complains with a deprecation warning.
754
To convert existing config files, the easiest way is to change the
755
section title: change "[options]" to "[general]". Most settings
756
haven't changed. The only ones to watch out for are these:
758
===================== =====================================
759
Old-Format Setting New Section & Setting
760
===================== =====================================
761
pep_stylesheet [pep_html writer] stylesheet
762
pep_stylesheet_path [pep_html writer] stylesheet_path
763
pep_template [pep_html writer] template
764
===================== =====================================
added
removed
docs/config.txt
