Docutils | Overview | About | Users | Reference | Developers

Docutils Runtime Settings

Author: David Goodger, Günter Milde
Contact: docutils-develop@lists.sourceforge.net
Date: 2024-08-15
Revision: 9906
Copyright: This document has been placed in the public domain.

Contents

Introduction

Docutils runtime settings are assembled from several sources:

The individual settings are described in Docutils Configuration.

Settings priority

Docutils overlays settings 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. Application defaults specified in the settings_overrides argument of the Publisher convenience functions.
  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).

Applications may opt-out of the standard settings processing providing their own set of settings.

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

Note

Implementation details will change with the move to replace the deprecated optparse module with argparse.

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

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 in the Docutils Configuration guide.

Glossary

components

Docutils front-ends and applications combine a selection of components of the Docutils Project Model (reader, parser, writer).

All components inherit the SettingsSpec base class. This means that all instances of readers.Reader, parsers.Parser, and writers.Writer are also instances of docutils.SettingsSpec.

For the determination of runtime settings, frontend.OptionParser and applications providing a SettingsSpec instance via the settings specification arguments of the Publisher convenience functions are treated as components as well.

settings_spec

The name settings_spec may refer to

  1. an instance of the SettingsSpec class,
  2. the data structure SettingsSpec.settings_spec which is used to store settings details, or
  3. the "settings_spec" argument of the Publisher convenience functions.