5
5
:Author: David Goodger
6
6
:Contact: goodger@python.org
7
:Date: $Date: 2005-06-27 13:25:47 +0200 (Mon, 27 Jun 2005) $
8
:Revision: $Revision: 3599 $
7
:Date: $Date: 2008-06-25 08:54:03 +0200 (Mit, 25 Jun 2008) $
8
:Revision: $Revision: 5576 $
9
9
:Copyright: This document has been placed in the public domain.
14
The ``docutils.core.Publisher`` class is the core of Docutils,
15
managing all the processing and relationships between components. See
16
`PEP 258`_ for an overview of Docutils components.
18
The ``docutils.core.publish_*`` convenience functions are the normal
19
entry points for using Docutils as a library.
21
See `Inside A Docutils Command-Line Front-End Tool`_ for an overview
22
of a typical Docutils front-end tool, including how the Publisher
25
.. _PEP 258: ../peps/pep-0258.html
26
.. _Inside A Docutils Command-Line Front-End Tool: ./cmdline-tool.html
14
29
Publisher Convenience Functions
15
30
===============================
17
32
Each of these functions set up a ``docutils.core.Publisher`` object,
18
33
then call its ``publish`` method. ``docutils.core.Publisher.publish``
19
handles everything else. There are five convenience functions in the
20
``docutils.core`` module:
34
handles everything else. There are several convenience functions in
35
the ``docutils.core`` module:
22
37
:_`publish_cmdline`: for command-line front-end tools, like
23
38
``rst2html.py``. There are several examples in the ``tools/``
40
55
There are usage examples in the `docutils/examples.py`_ module.
57
:_`publish_doctree`: for programmatic use with string input; returns a
58
Docutils document tree data structure (doctree). The doctree can be
59
modified, pickled & unpickled, etc., and then reprocessed with
60
`publish_from_doctree`_.
62
:_`publish_from_doctree`: for programmatic use to render from an
63
existing document tree data structure (doctree); returns the encoded
42
66
:_`publish_programmatically`: for custom programmatic use. This
43
67
function implements common code and is used by ``publish_file``,
44
68
``publish_string``, and ``publish_parts``. It returns a 2-tuple:
90
114
and values are Unicode strings.
92
116
Each Writer component may publish a different set of document parts,
93
described below. Currently only the HTML Writer implements more than
117
described below. Not all writers implement all parts.
97
120
Parts Provided By All Writers
98
121
-----------------------------
124
The output encoding setting.
127
The version of Docutils used.
101
130
``parts['whole']`` contains the entire formatted document.
104
135
Parts Provided By the HTML Writer
105
136
---------------------------------
108
139
``parts['body']`` is equivalent to parts['fragment_']. It is
109
140
*not* equivalent to parts['html_body_'].
143
``parts['body_prefix']`` contains::
147
<div class="document" ...>
156
``parts['body_pre_docinfo]`` contains (as applicable)::
158
<h1 class="title">...</h1>
159
<h2 class="subtitle" id="...">...</h2>
162
``parts['body_suffix']`` contains::
166
(the end-tag for ``<div class="document">``), the footer division
112
``parts['docinfo']`` contains the document bibliographic data.
179
``parts['docinfo']`` contains the document bibliographic data, the
180
docinfo field list rendered as a table.
115
183
``parts['footer']`` contains the document footer content, meant to
121
189
``<body>``). In other words, it contains the entire document,
122
190
less the document title, subtitle, docinfo, header, and footer.
193
``parts['head']`` contains ``<meta ... />`` tags and the document
194
``<title>...</title>``.
197
``parts['head_prefix']`` contains the XML declaration, the DOCTYPE
198
declaration, the ``<html ...>`` start tag and the ``<head>`` start
125
202
``parts['header']`` contains the document header content, meant to
126
203
appear at the top of a web page, or repeated at the top of every
163
240
``parts['meta']`` contains all ``<meta ... />`` tags.
166
``parts['stylesheet']`` contains the document stylesheet link.
243
``parts['stylesheet']`` contains the embedded stylesheet or
169
247
``parts['subtitle']`` contains the document subtitle text and any
174
252
``parts['title']`` contains the document title text and any inline
175
253
markup. It does not include the enclosing ``<h1>`` & ``</h1>``
257
Parts Provided by the PEP/HTML Writer
258
`````````````````````````````````````
260
The PEP/HTML writer provides the same parts as the `HTML writer`_,
264
``parts['pepnum']`` contains
267
Parts Provided by the S5/HTML Writer
268
````````````````````````````````````
270
The S5/HTML writer provides the same parts as the `HTML writer`_.
272
Parts Provided by the LaTeX2e Writer
273
````````````````````````````````````
276
``parts['head_prefix']`` contains the LaTeX document class, package
277
and stylesheet inclusion.
280
``parts['head']`` currently is empty.
283
``parts['body_prefix']`` contains the LaTeX ``\begin{document}`` and
287
``parts['body']`` contains the LaTeX document content, less
288
the ``\begin{document}`` and ``\end{document}`` tags themselves.
291
``parts['body_suffix']`` contains the LaTeX ``\end{document}``.
added
removed
docs/api/publisher.txt
