docs/api/runtime-settings.txt

   1 ===========================
   2  Docutils Runtime Settings
   3 ===========================
   4
   5 :Author: David Goodger
   6 :Contact: goodger@python.org
   7 :Date: $Date$
   8 :Revision: $Revision$
   9 :Copyright: This document has been placed in the public domain.
  10
  11 .. contents::
  12
  13
  14 Introduction
  15 ============
  16
  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
  22 behave.
  23
  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):
  28
  29 * ``settings_spec``
  30 * ``settings_defaults``
  31 * ``settings_default_overrides``
  32 * ``relative_path_settings``
  33 * ``config_section``
  34 * ``config_section_dependencies``
  35
  36 Next, several _`convenience function parameters` are also significant
  37 (described in the ``docutils.core.publish_programmatically`` function
  38 docstring):
  39
  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.
  46
  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
  50   "Application" itself.
  51
  52 * ``settings_overrides`` is a dictionary which will override the
  53   defaults of the components (from their settings specs).
  54
  55 * ``config_section`` specifies the name of an application-specific
  56   configuration file section.
  57
  58
  59 .. _command-line tools:
  60
  61 Runtime Settings Processing for Command-Line Tools
  62 ==================================================
  63
  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.
  67
  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.
  71
  72 2. ``docutils.core.publish_cmdline`` initializes a
  73    ``docutils.core.Publisher`` object, then calls its ``publish``
  74    method.
  75
  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.
  79
  80    If ``settings`` is not defined, ``self.process_command_line`` is
  81    called with the following relevant arguments:
  82
  83    * ``settings_spec``
  84    * ``config_section``
  85    * ``settings_overrides`` (in the form of excess keyword
  86      arguments, collected in the ``defaults`` parameter)
  87
  88 4. ``self.process_command_line`` calls ``self.setup_option_parser``,
  89    passing ``settings_spec``, ``config_section``, and ``defaults``.
  90
  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
  97    relevant arguments:
  98
  99    * ``components``: A tuple of ``docutils.SettingsSpec`` objects,
 100      ``(self.parser, self.reader, self.writer, settings_spec)``
 101    * ``defaults`` (originally from ``settings_overrides``)
 102
 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.
 108
 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.
 116
 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.
 122
 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
 131    defaults.
 132
 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``.
 136
 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
 142     settings.
 143
 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``.
 148
 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.
 154
 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``.
 161
 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``).
 165
 166 .. _Docutils Configuration Files: ../user/config.html
 167
 168
 169 Runtime Settings Processing From Applications
 170 =============================================
 171
 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).
 180
 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.
 188
 189 .. copy & modify the list from command-line tools?
 190
 191
 192 .. _Docutils-develop: ../user/mailing-lists.html#docutils-develop