Introduction

Docutils runtime settings are assembled from several sources:

• Settings specifications of the selected components,
• configuration files (if enabled), and
• command-line options (if enabled).

Docutils overlays default and explicitly specified values from these sources such that settings behave the way we want and expect them to behave.

Settings priority

The sources are overlaid in the following order (later sources overwrite earlier ones):

1. Defaults specified in the settings_spec and settings_defaults attributes for each component.
2. Defaults specified in the settings_default_overrides attribute for each component.
3. Settings specified in the settings_overrides parameter of the convenience functions resp. the settings_overrides attribute of a Publisher instance.
4. Settings specified in active sections of the configuration files in the order described in Configuration File Sections & Entries (if enabled).
5. Command line options (if enabled).

For details see the docutils/__init__.py, docutils/core.py, and docutils.frontend.py modules and the implementation description in Runtime Settings Processing.

SettingsSpec base class

The docutils.SettingsSpec base class is inherited by Docutils components and frontend.OptionParser. It defines the following six attributes:

settings_spec

a sequence of

1. option group title (string or None)
2. description (string or None)
3. option tuples with
   1. help text
   2. options string(s)
   3. dictionary with keyword arguments for OptionParser.add_option() and an optional "validator", a frontend.validate_*() function that processes the values (e.g. convert to other data types).

For examples, see the source of frontend.OptionParser.settings_spec or the settings_spec attributes of the Docutils components.

settings_defaults

for purely programmatic settings (not accessible from command line and configuration files).

settings_default_overrides

to override defaults for settings defined in other components' setting_specs.

relative_path_settings

listing settings containing filesystem paths.

config_section

the configuration file section specific to this component.

config_section_dependencies

lists configuration files sections that should also be read (before the config_section).

The last two attributes define which configuration file sections are "active". See also Configuration File Sections & Entries.

Glossary