diff options
Diffstat (limited to 'docutils/docs/api')
| -rw-r--r-- | docutils/docs/api/cmdline-tool.txt | 68 | ||||
| -rw-r--r-- | docutils/docs/api/publisher.txt | 176 | ||||
| -rw-r--r-- | docutils/docs/api/runtime-settings.txt | 192 |
3 files changed, 0 insertions, 436 deletions
diff --git a/docutils/docs/api/cmdline-tool.txt b/docutils/docs/api/cmdline-tool.txt deleted file mode 100644 index 3d3d4a635..000000000 --- a/docutils/docs/api/cmdline-tool.txt +++ /dev/null @@ -1,68 +0,0 @@ -=============================================== - 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/docutils/docs/api/publisher.txt b/docutils/docs/api/publisher.txt deleted file mode 100644 index 73cfc0ef2..000000000 --- a/docutils/docs/api/publisher.txt +++ /dev/null @@ -1,176 +0,0 @@ -======================== - 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/docutils/docs/api/runtime-settings.txt b/docutils/docs/api/runtime-settings.txt deleted file mode 100644 index 2d60aa3e1..000000000 --- a/docutils/docs/api/runtime-settings.txt +++ /dev/null @@ -1,192 +0,0 @@ -=========================== - 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 |