diff options
Diffstat (limited to 'docs/api')
| -rw-r--r-- | docs/api/cmdline-tool.txt | 68 | ||||
| -rw-r--r-- | docs/api/publisher.txt | 176 | ||||
| -rw-r--r-- | docs/api/runtime-settings.txt | 192 |
3 files changed, 436 insertions, 0 deletions
diff --git a/docs/api/cmdline-tool.txt b/docs/api/cmdline-tool.txt new file mode 100644 index 000000000..3d3d4a635 --- /dev/null +++ b/docs/api/cmdline-tool.txt @@ -0,0 +1,68 @@ +=============================================== + Inside A Docutils Command-Line Front-End Tool +=============================================== + +:Author: David Goodger +:Contact: goodger@python.org +:Date: $Date$ +: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 +bottom. + +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@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:: + + try: + import locale + locale.setlocale(locale.LC_ALL, '') + except: + pass + +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 diff --git a/docs/api/publisher.txt b/docs/api/publisher.txt new file mode 100644 index 000000000..73cfc0ef2 --- /dev/null +++ b/docs/api/publisher.txt @@ -0,0 +1,176 @@ +======================== + The Docutils Publisher +======================== + +:Author: David Goodger +:Contact: goodger@python.org +:Date: $Date$ +: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. + See `publish_parts Details`_ below. + + There are usage 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 +.. _docutils/examples.py: ../../docutils/examples.py + + +Configuration +------------- + +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 + + +Encodings +--------- + +The default output encoding of Docutils is UTF-8. If you have any +non-ASCII in your input text, you may have to do a bit more setup. +Docutils may introduce some non-ASCII text if you use +`auto-symbol footnotes`_ or the `"contents" directive`_. + +.. _auto-symbol footnotes: + ../ref/rst/restructuredtext.html#auto-symbol-footnotes +.. _"contents" directive: + ../ref/rst/directives.html#table-of-contents + + +``publish_parts`` Details +========================= + +The ``docutils.core.publish_parts`` convenience function returns a +dictionary of document parts. Dictionary keys are the names of parts, +and values are Unicode strings. + +Each Writer component may publish a different set of document parts, +described below. Currently only the HTML Writer implements more than +the "whole" part. + + +Parts Provided By All Writers +----------------------------- + +_`whole` + ``parts['whole']`` contains the entire formatted document. + + +Parts Provided By the HTML Writer +--------------------------------- + +_`body` + ``parts['body']`` is equivalent to parts['fragment_']. It is + *not* equivalent to parts['html_body_']. + +_`docinfo` + ``parts['docinfo']`` contains the document bibliographic data. + +_`footer` + ``parts['footer']`` contains the document footer content, meant to + appear at the bottom of a web page, or repeated at the bottom of + every printed page. + +_`fragment` + ``parts['fragment']`` contains the document body (*not* the HTML + ``<body>``). In other words, it contains the entire document, + less the document title, subtitle, docinfo, header, and footer. + +_`header` + ``parts['header']`` contains the document header content, meant to + appear at the top of a web page, or repeated at the top of every + printed page. + +_`html_body` + ``parts['html_body']`` contains the HTML ``<body>`` content, less + the ``<body>`` and ``</body>`` tags themselves. + +_`html_head` + ``parts['html_head']`` contains the HTML ``<head>`` content, less + the stylesheet link and the ``<head>`` and ``</head>`` tags + themselves. Since ``publish_parts`` returns Unicode strings and + does not know about the output encoding, the "Content-Type" meta + tag's "charset" value is left unresolved, as "%s":: + + <meta http-equiv="Content-Type" content="text/html; charset=%s" /> + + The interpolation should be done by client code. + +_`html_prolog` + ``parts['html_prolog]`` contains the XML declaration and the + doctype declaration. The XML declaration's "encoding" attribute's + value is left unresolved, as "%s":: + + <?xml version="1.0" encoding="%s" ?> + + The interpolation should be done by client code. + +_`html_subtitle` + ``parts['html_subtitle']`` contains the document subtitle, + including the enclosing ``<h2 class="subtitle">`` & ``</h2>`` + tags. + +_`html_title` + ``parts['html_title']`` contains the document title, including the + enclosing ``<h1 class="title">`` & ``</h1>`` tags. + +_`meta` + ``parts['meta']`` contains all ``<meta ... />`` tags. + +_`stylesheet` + ``parts['stylesheet']`` contains the document stylesheet link. + +_`subtitle` + ``parts['subtitle']`` contains the document subtitle text and any + inline markup. It does not include the enclosing ``<h2>`` & + ``</h2>`` tags. + +_`title` + ``parts['title']`` contains the document title text and any inline + markup. It does not include the enclosing ``<h1>`` & ``</h1>`` + tags. diff --git a/docs/api/runtime-settings.txt b/docs/api/runtime-settings.txt new file mode 100644 index 000000000..2d60aa3e1 --- /dev/null +++ b/docs/api/runtime-settings.txt @@ -0,0 +1,192 @@ +=========================== + Docutils Runtime Settings +=========================== + +:Author: David Goodger +:Contact: goodger@python.org +:Date: $Date$ +:Revision: $Revision$ +:Copyright: This document has been placed in the public domain. + +.. contents:: + + +Introduction +============ + +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 +behave. + +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 +docstring): + +* The ``settings`` parameter is a runtime settings + (``docutils.frontend.Values``) object which, if present, is assumed + to be complete (it must include all runtime settings). Also, if the + ``settings`` parameter is present, no further runtime settings + processing is done. In other words, the other parameters, described + below, will have no effect. + +* ``settings_spec``, a `docutils.SettingsSpec` subclass or object, is + treated like a fourth component (after the Parser, Reader, and + Writer). In other words, it's the settings specification for the + "Application" itself. + +* ``settings_overrides`` is a dictionary which will override the + defaults of the components (from their settings specs). + +* ``config_section`` specifies the name of 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.py`` 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`` + method. + +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 + defaults. + +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 + settings. + + 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, + ``docutils.io.FileInput``. + +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/config.html + + +Runtime Settings Processing From Applications +============================================= + +Applications process runtime settings in a 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 no command-line processing. Instead of calling +``docutils.Publisher.process_command_line`` (as ``publish_cmdline`` +does, via ``docutils.Publisher.publish``), +``docutils.Publisher.process_programmatic_settings`` is called to set +up the runtime settings. + +.. copy & modify the list from command-line tools? + + +.. _Docutils-develop: ../user/mailing-lists.html#docutils-develop |