Docutils | Overview | About | Users | Reference | Developers

Docutils Runtime Settings

Author: David Goodger, Günter Milde
Contact: docutils-develop@lists.sourceforge.net
Date: 2022-04-02
Revision: 9051
Copyright: This document has been placed in the public domain.

Contents

Introduction

Docutils runtime settings are assembled from several sources:

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

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

components

Docutils front-ends and applications combine a selection of components of the Docutils Project Model.

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 the settings_spec parameter in application settings specifications are treated as components as well.

convenience functions

Applications usually deploy Docutils by one of the Publisher convenience functions.

All convenience functions accept the following optional parameters:

settings

a frontend.Values instance. If present, it must be complete.

No further runtime settings processing is done and the following parameters have no effect.

settings_spec
a SettingsSpec subclass or instance containing the settings specification for the "Application" itself. The instance is added to the components (after the generic settings, parser, reader, and writer).
settings_overrides
a dictionary which is used to update the defaults of the components' settings specifications.
config_section

the name of an application-specific configuration file section for this application.

Can be specified instead of a settings_spec (a new SettingsSpec instance that just defines a configuration section will be created) or in addition to a settings_spec (overriding its config_section attribute).

settings_spec

The name settings_spec may refer to

  1. an instance of the SettingsSpec class, or
  2. the data structure SettingsSpec.settings_spec which is used to store settings details.