1 ===========================
2 Docutils Runtime Settings
3 ===========================
6 :Contact: docutils-develop@lists.sourceforge.net
9 :Copyright: This document has been placed in the public domain.
17 Docutils runtime settings are assembled from several sources:
18 component settings specifications, application settings
19 specifications, configuration files, and command-line options.
20 Docutils overlays default and explicitly specified values from these
21 sources such that settings behave the way we want and expect them to
24 To understand how Docutils deals with runtime settings, the attributes
25 and parameters involved must first be understood. Begin with the the
26 docstrings of the attributes of the ``docutils.SettingsSpec`` base
27 class (in the ``docutils/__init__.py`` module):
30 * ``settings_defaults``
31 * ``settings_default_overrides``
32 * ``relative_path_settings``
34 * ``config_section_dependencies``
36 Next, several _`convenience function parameters` are also significant
37 (described in the ``docutils.core.publish_programmatically`` function
40 * The ``settings`` parameter is a runtime settings
41 (``docutils.frontend.Values``) object which, if present, is assumed
42 to be complete (it must include all runtime settings). Also, if the
43 ``settings`` parameter is present, no further runtime settings
44 processing is done. In other words, the other parameters, described
45 below, will have no effect.
47 * ``settings_spec``, a `docutils.SettingsSpec` subclass or object, is
48 treated like a fourth component (after the Parser, Reader, and
49 Writer). In other words, it's the settings specification for the
52 * ``settings_overrides`` is a dictionary which will override the
53 defaults of the components (from their settings specs).
55 * ``config_section`` specifies the name of an application-specific
56 configuration file section.
59 .. _command-line tools:
61 Runtime Settings Processing for Command-Line Tools
62 ==================================================
64 Following along with the actual code is recommended. The
65 ``docutils/__init__.py``, ``docutils/core.py``, and
66 ``docutils.frontend.py`` modules are described.
68 1. A command-line front-end tool imports and calls
69 ``docutils.core.publish_cmdline``. The relevant `convenience
70 function parameters`_ are described above.
72 2. ``docutils.core.publish_cmdline`` initializes a
73 ``docutils.core.Publisher`` object, then calls its ``publish``
76 3. The ``docutils.core.Publisher`` object's ``publish`` method checks
77 its ``settings`` attribute to see if it's defined. If it is, no
78 further runtime settings processing is done.
80 If ``settings`` is not defined, ``self.process_command_line`` is
81 called with the following relevant arguments:
85 * ``settings_overrides`` (in the form of excess keyword
86 arguments, collected in the ``defaults`` parameter)
88 4. ``self.process_command_line`` calls ``self.setup_option_parser``,
89 passing ``settings_spec``, ``config_section``, and ``defaults``.
91 5. ``self.setup_option_parser`` checks its ``config_section``
92 parameter; if defined, it adds that config file section to
93 ``settings_spec`` (or to a new, empty ``docutils.SettingsSpec``
94 object), replacing anything defined earlier. (See `Docutils
95 Configuration Files`_ for details.) Then it instantiates a new
96 ``docutils.frontend.OptionParser`` object, passing the following
99 * ``components``: A tuple of ``docutils.SettingsSpec`` objects,
100 ``(self.parser, self.reader, self.writer, settings_spec)``
101 * ``defaults`` (originally from ``settings_overrides``)
103 6. The ``docutils.frontend.OptionParser`` object's ``__init__`` method
104 calls ``self.populate_from_components`` with ``self.components``,
105 which consists of ``self`` prepended to the ``components`` tuple it
106 received. ``self`` (``docutils.frontend.OptionParser``) defines
107 general Docutils settings.
109 7. In ``self.populate_from_components``, for each component passed,
110 ``component.settings_spec`` is processed and
111 ``component.settings_defaults`` is applied. Then, for each
112 component, ``component.settings_default_overrides`` is applied.
113 This two-loop process ensures that
114 ``component.settings_default_overrides`` can override the default
115 settings of any other component.
117 8. Back in ``docutils.frontend.OptionParser.__init__``, the
118 ``defaults`` parameter (derived from the ``settings_overrides``
119 parameter of ``docutils.core.Publisher.publish``) is overlaid over
120 ``self.defaults``. So ``settings_overrides`` has priority over all
121 ``SettingsSpec`` data.
123 9. Next, ``docutils.frontend.OptionParser.__init__`` checks if
124 configuration files are enabled (its ``read_config_files``
125 parameter is true, and ``self.defaults['_disable_config']`` is
126 false). If they are enabled (and normally, they are),
127 ``self.get_standard_config_settings`` is called. This reads the
128 `docutils configuration files`_, and returns a dictionary of
129 settings. This is then overlaid on ``self.defaults``. So
130 configuration file settings have priority over all software-defined
133 10. Back in the ``docutils.core.Publisher`` object,
134 ``self.setup_option_parser`` returns the ``option_parser`` object
135 to its caller, ``self.process_command_line``.
137 11. ``self.process_command_line`` calls ``option_parser.parse_args``,
138 which parses all command line options and returns a
139 ``docutils.frontend.Values`` object. This is assigned to the
140 ``docutils.core.Publisher`` object's ``self.settings``. So
141 command-line options have priority over configuration file
144 When ``option_parser.parse_args`` is called, the source and
145 destination command-line arguments are also parsed, and assigned
146 to the ``_source`` and ``_destination`` attributes of what becomes
147 the ``docutils.core.Publisher`` object's ``self.settings``.
149 12. From ``docutils.core.Publisher.publish``, ``self.set_io`` is
150 called with no arguments. If either ``self.source`` or
151 ``self.destination`` are not set, the corresponding
152 ``self.set_source`` and ``self.set_destination`` are called,
153 effectively with no arguments.
155 13. ``self.set_source`` checks for a ``source_path`` parameter, and if
156 there is none (which is the case for command-line use), it is
157 taken from ``self.settings._source``. ``self.source`` is set by
158 instantiating a ``self.source_class`` object. For command-line
159 front-end tools, the default ``self.source_class`` is used,
160 ``docutils.io.FileInput``.
162 14. ``self.set_destination`` does the same job for the destination
163 that ``self.set_source`` does for the source (the default
164 ``self.destination_class`` is ``docutils.io.FileOutput``).
166 .. _Docutils Configuration Files: ../user/config.html
169 Runtime Settings Processing From Applications
170 =============================================
172 Applications process runtime settings in a different way than
173 `command-line tools`_ do. Instead of calling ``publish_cmdline``, the
174 application calls one of ``publish_file``, ``publish_string``, or
175 ``publish_parts``. These in turn call ``publish_programmatically``,
176 which implements a generic programmatic interface. Although an
177 application may also call ``publish_programmatically`` directly, it is
178 not recommended (if it does seem to be necessary, please write to the
179 Docutils-develop_ mailing list).
181 ``publish_programmatically`` accepts the same `convenience function
182 parameters`_ as ``publish_cmdline``. Where things differ is that
183 programmatic use does no command-line processing. Instead of calling
184 ``docutils.Publisher.process_command_line`` (as ``publish_cmdline``
185 does, via ``docutils.Publisher.publish``),
186 ``docutils.Publisher.process_programmatic_settings`` is called to set
187 up the runtime settings.
189 .. copy & modify the list from command-line tools?
192 .. _Docutils-develop: ../user/mailing-lists.html#docutils-develop