Author: David Goodger
Date: 2012-01-03

# The Docutils Publisher

Author: | David Goodger
Contact: | docutils-develop@lists.sourceforge.net
Date: | 2012-01-03
Revision: | 7302
Copyright: | This document has been placed in the public domain.

Contents

- Publisher Convenience Functions
  - Configuration
  - Encodings
- `publish_parts` Details
  - Parts Provided By All Writers
  - Parts Provided By the HTML Writer
    - Parts Provided by the PEP/HTML Writer
    - Parts Provided by the S5/HTML Writer
  - Parts Provided by the LaTeX2e Writer

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.

# 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.

## 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.

## 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.

# `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.

## 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:

      </head>
      <body>
      <div class="document" ...>

  and, if applicable:

      <div class="header">
      ...
      </div>

body_pre_docinfo

  `parts['body_pre_docinfo]` contains (as applicable):

      <h1 class="title">...</h1>
      <h2 class="subtitle" id="...">...</h2>

body_suffix

  `parts['body_suffix']` contains:

      </div>

  (the end-tag for `<div class="document">`), the footer division if applicable:

      <div class="footer">
      ...
      </div>

  and:

      </body>
      </html>

docinfo
  `parts['docinfo']` contains the document bibliographic data, the docinfo field list rendered as a table.
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.
head
  `parts['head']` contains `<meta ... />` tags and the document `<title>...</title>`.
head_prefix
  `parts['head_prefix']` contains the XML declaration, the DOCTYPE declaration, the `<html ...>` start tag and the `<head>` start tag.
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 embedded stylesheet or 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.

### Parts Provided by the PEP/HTML Writer

The PEP/HTML writer provides the same parts as the HTML writer, plus the following:

pepnum
  `parts['pepnum']` contains

### Parts Provided by the S5/HTML Writer

The S5/HTML writer provides the same parts as the HTML writer.

## Parts Provided by the LaTeX2e Writer

See the template files for examples how these parts can be combined into a valid LaTeX document.

abstract
  `parts['abstract']` contains the formatted content of the 'abstract' docinfo field.
body

  `parts['body']` contains the document's content. In other words, it contains the entire document, except the document title, subtitle, and docinfo.

  This part can be included into another LaTeX document body using the `\input{}` command.

body_pre_docinfo
  `parts['body_pre_docinfo]` contains the `\maketitle` command.
dedication
  `parts['dedication']` contains the formatted content of the 'dedication' docinfo field.
docinfo

  `parts['docinfo']` contains the document bibliographic data, the docinfo field list rendered as a table.

  With `--use-latex-docinfo` 'author', 'organization', 'contact', 'address' and 'date' info is moved to titledata.

  'dedication' and 'abstract' are always moved to separate parts.

fallbacks
  `parts['fallbacks']` contains fallback definitions for Docutils-specific commands and environments.
head_prefix
  `parts['head_prefix']` contains the declaration of documentclass and document options.
latex_preamble
  `parts['latex_preamble']` contains the argument of the `--latex-preamble` option.
pdfsetup
  `parts['pdfsetup']` contains the PDF properties ("hyperref" package setup).
requirements
  `parts['requirements']` contains required packages and setup before the stylesheet inclusion.
stylesheet
  `parts['stylesheet']` contains the embedded stylesheet(s) or stylesheet loading command(s).
subtitle
  `parts['subtitle']` contains the document subtitle text and any inline markup.
title
  `parts['title']` contains the document title text and any inline markup.
titledata

  `parts['titledata]` contains the combined title data in `\title`, `\author`, and `\data` macros.

  With `--use-latex-docinfo`, this includes the 'author', 'organization', 'contact', 'address' and 'date' docinfo items.