[Zope-Checkins] CVS: Zope/lib/python/third_party/docutils/docs/api - cmdline-tool.txt: publisher.txt: runtime-settings.txt:

Andreas Jung andreas at andreas-jung.com
Fri Oct 29 14:24:45 EDT 2004

Update of /cvs-repository/Zope/lib/python/third_party/docutils/docs/api
In directory cvs.zope.org:/tmp/cvs-serv11767/docutils/docs/api

Added Files:
      Tag: ajung-docutils-cleanup-branch
	cmdline-tool.txt publisher.txt runtime-settings.txt 
Log Message:

=== Added File Zope/lib/python/third_party/docutils/docs/api/cmdline-tool.txt ===
 Inside A Docutils Command-Line Front-End Tool

:Author: David Goodger
:Contact: goodger at python.org
:Date: $Date: 2004/10/29 18:24:44 $
:Revision: $Revision: $
:Copyright: This document has been placed in the public domain.

`The Docutils Publisher`_ class was set up to make building
command-line tools easy.  All that's required is to choose components
and supply settings for variations.  Let's take a look at a typical
command-line front-end tool, ``tools/rst2html.py``, from top to

On Unixish systems, it's best to make the file executable (``chmod +x
file``), and supply an interpreter on the first line, the "shebang" or
"hash-bang" line::

    #!/usr/bin/env python

Windows systems can be set up to associate the Python interpreter with
the ``.py`` extension.

Next are some comments providing metadata::

    # Author: David Goodger
    # Contact: goodger at python.org
    # Revision: $Revision: ...
    # Date: $Date: ...
    # Copyright: This module has been placed in the public domain.

The module docstring describes the purpose of the tool::

    A minimal front end to the Docutils Publisher, producing HTML.

This next block attempts to invoke locale support for
internationalization services, specifically text encoding.  It's not
supported on all platforms though, so it's forgiving::

        import locale
        locale.setlocale(locale.LC_ALL, '')

The real work will be done by the code that's imported here::

    from docutils.core import publish_cmdline, default_description

We construct a description of the tool, for command-line help::

    description = ('Generates (X)HTML documents from standalone '
                   'reStructuredText sources.  ' + default_description)

Now we call the Publisher convenience function, which takes over.
Most of it's defaults are used ("standalone" Reader,
"reStructuredText" Parser, etc.).  The HTML Writer is chosen by name,
and a description for command-line help is passed in::

    publish_cmdline(writer_name='html', description=description)

That's it!  `The Docutils Publisher`_ takes care of the rest.

.. _The Docutils Publisher: ./publisher.html

=== Added File Zope/lib/python/third_party/docutils/docs/api/publisher.txt ===
 The Docutils Publisher

:Author: David Goodger
:Contact: goodger at python.org
:Date: $Date: 2004/10/29 18:24:44 $
:Revision: $Revision: $
:Copyright: This document has been placed in the public domain.

.. contents::

Publisher Convenience Functions

Each of these functions set up a ``docutils.core.Publisher`` object,
then call its ``publish`` method.  ``docutils.core.Publisher.publish``
handles everything else.  There are five convenience functions in the
``docutils.core`` module:

* ``publish_cmdline``: for command-line front-end tools, like
  ``rst2html.py``.  There are several examples in the ``tools/``
  directory.  A detailed analysis of one such tool is in `Inside A
  Docutils Command-Line Front-End Tool`_

* ``publish_file``: for programmatic use with file-like I/O.  In
  addition to writing the encoded output to a file, also returns the
  encoded output as a string.

* ``publish_string``: for programmatic use with string I/O.  Returns
  the encoded output as a string.

* ``publish_parts``: for programmatic use with string input; returns a
  dictionary of document parts.  Dictionary keys are the names of
  parts, and values are Unicode strings; encoding is up to the client.
  Useful when only portions of the processed document are desired.
  Currently only implemented for the HTML Writer.

  There are examples in the ``docutils/examples.py`` module.

* ``publish_programmatically``: for custom programmatic use.  This
  function implements common code and is used by ``publish_file``,
  ``publish_string``, and ``publish_parts``.  It returns a 2-tuple:
  the encoded string output and the Publisher object.

.. _Inside A Docutils Command-Line Front-End Tool: ./cmdline-tool.html


To pass application-specific setting defaults to the Publisher
convenience functions, use the ``settings_overrides`` parameter.  Pass
a dictionary of setting names & values, like this::

    overrides = {'input_encoding': 'ascii',
                 'output_encoding': 'latin-1'}
    output = publish_string(..., settings_overrides=overrides)

Settings from command-line options override configuration file
settings, and they override application defaults.  For details, see
`Docutils Runtime Settings`_.  See `Docutils Configuration Files`_ for
details about individual settings.

.. _Docutils Runtime Settings: ./runtime-settings.html
.. _Docutils Configuration Files: ../user/tools.html


The default output encoding of Docutils is UTF-8.  If you have any
non-ASCII in your text, you may have to do a bit more setup.  Docutils
may introduce some non-ASCII text if you use symbol-footnotes or
section numbering.

=== Added File Zope/lib/python/third_party/docutils/docs/api/runtime-settings.txt ===
 Docutils Runtime Settings

:Author: David Goodger
:Contact: goodger at python.org
:Date: $Date: 2004/10/29 18:24:44 $
:Revision: $Revision: $
:Copyright: This document has been placed in the public domain.

.. contents::


Docutils runtime settings are assembled from several sources:
component settings specifications, application settings
specifications, configuration files, and command-line options.
Docutils overlays default and explicitly specified values from these
sources such that settings behave the way we want and expect them to

To understand how Docutils deals with runtime settings, the attributes
and parameters involved must first be understood.  Begin with the the
docstrings of the attributes of the ``docutils.SettingsSpec`` base
class (in the ``docutils/__init__.py`` module):

* ``settings_spec``
* ``settings_defaults``
* ``settings_default_overrides``
* ``relative_path_settings``
* ``config_section``
* ``config_section_dependencies``

Next, several _`convenience function parameters` are also significant
(described in the ``docutils.core.publish_programmatically`` function

* ``settings``, if present, is assumed to be complete and no further
  runtime settings processing is done.

* ``settings_spec`` is treated as a fourth component (after the
  Parser, Reader, and Writer).

* ``settings_overrides`` is a dictionary which will override the
  defaults of the components.

* ``config_section`` sets or overrides an application-specific
  configuration file section.

.. _command-line tools:

Runtime Settings Processing for Command-Line Tools

Following along with the actual code is recommended.  The
``docutils/__init__.py``, ``docutils/core.py``, and
``docutils.frontend`` modules are described.

1. A command-line front-end tool imports and calls
   ``docutils.core.publish_cmdline``.  The relevant `convenience
   function parameters`_ are described above.

2. ``docutils.core.publish_cmdline`` initializes a
   ``docutils.core.Publisher`` object, then calls its ``publish``

3. The ``docutils.core.Publisher`` object's ``publish`` method checks
   its ``settings`` attribute to see if it's defined.  If it is, no
   further runtime settings processing is done.

   If ``settings`` is not defined, ``self.process_command_line`` is
   called with the following relevant arguments:

   * ``settings_spec``
   * ``config_section``
   * ``settings_overrides`` (in the form of excess keyword
     arguments, collected in the ``defaults`` parameter)

4. ``self.process_command_line`` calls ``self.setup_option_parser``,
   passing ``settings_spec``, ``config_section``, and ``defaults``.

5. ``self.setup_option_parser`` checks its ``config_section``
   parameter; if defined, it adds that config file section to
   ``settings_spec`` (or to a new, empty ``docutils.SettingsSpec``
   object), replacing anything defined earlier.  (See `Docutils
   Configuration Files`_ for details.)  Then it instantiates a new
   ``docutils.frontend.OptionParser`` object, passing the following
   relevant arguments:

   * ``components``: A tuple of ``docutils.SettingsSpec`` objects,
     ``(self.parser, self.reader, self.writer, settings_spec)``
   * ``defaults`` (originally from ``settings_overrides``)

6. The ``docutils.frontend.OptionParser`` object's ``__init__`` method
   calls ``self.populate_from_components`` with ``self.components``,
   which consists of ``self`` prepended to the ``components`` tuple it
   received.  ``self`` (``docutils.frontend.OptionParser``) defines
   general Docutils settings.

7. In ``self.populate_from_components``, for each component passed,
   ``component.settings_spec`` is processed and
   ``component.settings_defaults`` is applied.  Then, for each
   component, ``component.settings_default_overrides`` is applied.
   This two-loop process ensures that
   ``component.settings_default_overrides`` can override the default
   settings of any other component.

8. Back in ``docutils.frontend.OptionParser.__init__``, the
   ``defaults`` parameter (derived from the ``settings_overrides``
   parameter of ``docutils.core.Publisher.publish``) is overlaid over
   ``self.defaults``.  So ``settings_overrides`` has priority over all
   ``SettingsSpec`` data.

9. Next, ``docutils.frontend.OptionParser.__init__`` checks if
   configuration files are enabled (its ``read_config_files``
   parameter is true, and ``self.defaults['_disable_config']`` is
   false).  If they are enabled (and normally, they are),
   ``self.get_standard_config_settings`` is called.  This reads the
   `docutils configuration files`_, and returns a dictionary of
   settings.  This is then overlaid on ``self.defaults``.  So
   configuration file settings have priority over all software-defined

10. Back in the ``docutils.core.Publisher`` object,
    ``self.setup_option_parser`` returns the ``option_parser`` object
    to its caller, ``self.process_command_line``.

11. ``self.process_command_line`` calls ``option_parser.parse_args``,
    which parses all command line options and returns a
    ``docutils.frontend.Values`` object.  This is assigned to the
    ``docutils.core.Publisher`` object's ``self.settings``.  So
    command-line options have priority over configuration file

    When ``option_parser.parse_args`` is called, the source and
    destination command-line arguments are also parsed, and assigned
    to the ``_source`` and ``_destination`` attributes of what becomes
    the ``docutils.core.Publisher`` object's ``self.settings``.

12. From ``docutils.core.Publisher.publish``, ``self.set_io`` is
    called with no arguments.  If either ``self.source`` or
    ``self.destination`` are not set, the corresponding
    ``self.set_source`` and ``self.set_destination`` are called,
    effectively with no arguments.

13. ``self.set_source`` checks for a ``source_path`` parameter, and if
    there is none (which is the case for command-line use), it is
    taken from ``self.settings._source``.  ``self.source`` is set by
    instantiating a ``self.source_class`` object.  For command-line
    front-end tools, the default ``self.source_class`` is used,

14. ``self.set_destination`` does the same job for the destination
    that ``self.set_source`` does for the source (the default
    ``self.destination_class`` is ``docutils.io.FileOutput``).

.. _Docutils Configuration Files: ../user/tools.html

Runtime Settings Processing From Applications

Applications process runtime settings in a significantly different way
than `command-line tools`_ do.  Instead of calling
``publish_cmdline``, the application calls one of ``publish_file``,
``publish_string``, or ``publish_parts``.  These in turn call
``publish_programmatically``, which implements a generic programmatic
interface.  Although an application may also call
``publish_programmatically`` directly, it is not recommended (if it
does seem to be necessary, please write to the `Docutils-Develop
mailing list`_).

``publish_programmatically`` accepts the same `convenience function
parameters`_ as ``publish_cmdline``.  Where things differ is that
programmatic use does not


.. copy & modify the list from command-line tools?

.. _Docutils-Develop mailing list: docutils-develop at lists.sf.net

More information about the Zope-Checkins mailing list