docs.api.publisher.txt Maven / Gradle / Ivy
========================
The Docutils Publisher
========================
:Author: David Goodger
:Contact: [email protected]
:Date: $Date: 2012-01-03 20:23:53 +0100 (Die, 03 Jän 2012) $
:Revision: $Revision: 7302 $
:Copyright: This document has been placed in the public domain.
.. contents::
The ``docutils.core.Publisher`` class is the core of Docutils,
managing all the processing and relationships between components. See
`PEP 258`_ for an overview of Docutils components.
The ``docutils.core.publish_*`` convenience functions are the normal
entry points for using Docutils as a library.
See `Inside A Docutils Command-Line Front-End Tool`_ for an overview
of a typical Docutils front-end tool, including how the Publisher
class is used.
.. _PEP 258: ../peps/pep-0258.html
.. _Inside A Docutils Command-Line Front-End Tool: ./cmdline-tool.html
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 several 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_doctree`: for programmatic use with string input; returns a
Docutils document tree data structure (doctree). The doctree can be
modified, pickled & unpickled, etc., and then reprocessed with
`publish_from_doctree`_.
:_`publish_from_doctree`: for programmatic use to render from an
existing document tree data structure (doctree); returns the encoded
output as a string.
:_`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. Not all writers implement all parts.
Parts Provided By All Writers
-----------------------------
_`encoding`
The output encoding setting.
_`version`
The version of Docutils used.
_`whole`
``parts['whole']`` contains the entire formatted document.
.. _HTML writer:
Parts Provided By the HTML Writer
---------------------------------
_`body`
``parts['body']`` is equivalent to parts['fragment_']. It is
*not* equivalent to parts['html_body_'].
_`body_prefix`
``parts['body_prefix']`` contains::
and, if applicable::
...
_`body_pre_docinfo`
``parts['body_pre_docinfo]`` contains (as applicable)::
...
...
_`body_suffix`
``parts['body_suffix']`` contains::
(the end-tag for ````), the footer division
if applicable::
and::