docutils.__main__ module

Generic command line interface for the docutils package.

See also https://docs.python.org/3/library/__main__.html#main-py-in-python-packages

class CliSettingsSpec[source]

Bases: SettingsSpec

Runtime settings & command-line options for the generic CLI.

Configurable reader, parser, and writer components.

The “–writer” default will change to ‘html’ in Docutils 2.0 when ‘html’ becomes an alias for the current value ‘html5’.

settings_spec = ('Docutils Application Options', 'Reader, writer, and parser settings influence the available options.   Example: use `--help --writer=latex` to see LaTeX writer options. ', (('Reader name (currently: "%default").', ['--reader'], {'default': 'standalone', 'metavar': '<reader>'}), ('Parser name (currently: "%default").', ['--parser'], {'default': 'rst', 'metavar': '<parser>'}), ('Writer name (currently: "%default").', ['--writer'], {'default': 'html5', 'metavar': '<writer>'})))

Runtime settings specification. Override in subclasses.

Defines runtime settings and associated command-line options, as used by docutils.frontend.OptionParser. This is a tuple of:

  • Option group title (string or None which implies no group, just a list of single options).

  • Description (string or None).

  • A sequence of option tuples. Each consists of:

    • Help text (string)

    • List of option strings (e.g. ['-Q', '--quux']).

    • Dictionary of keyword arguments sent to the OptionParser/OptionGroup add_option method.

      Runtime setting names are derived implicitly from long option names (’–a-setting’ becomes settings.a_setting) or explicitly from the ‘dest’ keyword argument.

      Most settings will also have a ‘validator’ keyword & function. The validator function validates setting values (from configuration files and command-line option arguments) and converts them to appropriate types. For example, the docutils.frontend.validate_boolean function, required by all boolean settings, converts true values (‘1’, ‘on’, ‘yes’, and ‘true’) to 1 and false values (‘0’, ‘off’, ‘no’, ‘false’, and ‘’) to 0. Validators need only be set once per setting. See the docutils.frontend.validate_* functions.

      See the optparse docs for more details.

  • More triples of group title, description, options, as many times as needed. Thus, settings_spec tuples can be simply concatenated.

config_section = 'docutils application'

The name of the config file section specific to this component (lowercase, no brackets). Override in subclasses.

config_section_dependencies = ('docutils-cli application', 'applications')

A list of names of config file sections that are to be applied before config_section, in order (from general to specific). In other words, the settings in config_section are to be overlaid on top of the settings from these sections. The “general” section is assumed implicitly. Override in subclasses.

main()[source]

Generic command line interface for the Docutils Publisher.