Docutils Runtime Settings (original) (raw)

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
• Settings priority
• SettingsSpec base class
  • attributes
• Glossary
  • components
  • settings_spec

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

1. Defaults specified in the settings_spec andsettings_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 filesin 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, anddocutils.frontend.py modules and the implementation description inRuntime Settings Processing.

SettingsSpec base class

The docutils.SettingsSpec base class is inherited by Docutilscomponents 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_specor 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, andwriters.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 functionsare 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.