Docutils Runtime Settings
- Contact:
- docutils-develop@lists.sourceforge.net
- Date:
- 2024-08-15
- Revision:
- 9906
- Copyright:
- This document has been placed in the public domain.
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).
The individual settings are described in Docutils Configuration.
Settings priority
Docutils overlays settings in the following order (later sources overwrite earlier ones):
Defaults specified in the settings_spec and settings_defaults attributes for each component.
Defaults specified in the settings_default_overrides attribute for each component.
Application defaults specified in the settings_overrides argument of the Publisher convenience functions.
Settings specified in active sections of the configuration files in the order described in Configuration File Sections & Entries (if enabled).
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
The docutils.SettingsSpec base class is inherited by Docutils components and frontend.OptionParser. It defines six attributes:
attributes
- settings_spec
a sequence of
option group title (string or None)
description (string or None)
option tuples with
help text
options string(s)
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
an instance of the SettingsSpec class,
the data structure SettingsSpec.settings_spec which is used to store settings details, or
the "settings_spec" argument of the Publisher convenience functions.