Quickstart

This section gets you started quickly, discussing each of the three modes of operation introduced in Introduction. If you want to customize the style of the PDF document, please refer to Basic Document Styling which introduces style sheets and document templates.

Command-Line Renderer

Installing rinohtype places the rinoh script in the PATH. This can be used to render structured documents such as demo.txt (reStructuredText):

rinoh --format reStructuredText demo.txt

After rendering finishes, you will find demo.pdf alongside the input file.

rinoh allows specifying the document template and style sheet to use when rendering the reStructuredText document. See its command-line options for details.

Two rendering passes are required to make sure that cross-references to page numbers are correct. After a document has been rendered, rinohtype will save the page reference data to a .rtc file. Provided the document (or the template or style sheet) doesn’t change a lot, this can prevent the need to perform a second rendering pass.

Sphinx Builder

To use rinohtype to render Sphinx documents, at a minimum you need to add 'rinoh.frontend.sphinx' to the extensions list in the Sphinx project’s conf.py.

If your Sphinx project is already configured for rendering with LaTeX, rinohtype will happily interpret latex_documents and other options for the LaTeX builder. Otherwise, you need to set the rinoh_documents configuration option:

rinoh_documents = [('index',            # top-level file (index.rst)
                    'target',           # output (target.pdf)
                    'Document Title',   # document title
                    'John A. Uthor')]   # document author

Other configuration variables are optional and allow configuring the style of the generated PDF document. See Sphinx Builder for details.

When building the documentation, select the rinoh builder by passing it to sphinx-build -b option:

sphinx-build -b rinoh . _build/rinoh

Just like the rinoh command line tool, the Sphinx builder requires two rendering passes.

High-level PDF Library

Note

The focus of rinohtype development is currently on the rinoh tool and Sphinx builder. Use as a Python library is possible, but documentation may be lacking. Please be patient.

The most basic way to use rinohtype in an application is to hook up an included frontend, a document template and a style sheet:

from rinoh.frontend.rst import ReStructuredTextReader
from rinoh.templates import Article

# the parser builds a rinohtype document tree
parser = ReStructuredTextReader()
with open('my_document.rst') as file:
    document_tree = parser.parse(file)

# render the document to 'my_document.pdf'
document = Article(document_tree)
document.render('my_document')

This basic application can be customized to your specific requirements by customizing the document template, the style sheet and the way the document’s content tree is built. The basics of document templates and style sheets are covered the the sections below.

The document tree returned by the ReStructuredTextReader in the example above can also be built manually. A DocumentTree is simply a list of Flowables, which can have child elements. These children in turn can also have children, and so on; together they form a tree.

Here is an example document tree of a short article:

from rinoh.document import DocumentTree
from rinoh.styleds import *

document_tree = DocumentTree(
                    [Paragraph('My Document', style='title'), # metadata!
                     Section([Heading('First Section'),
                              Paragraph('This is a paragraph with some '
                                        + StyledText('emphasized text',
                                                     style='emphasis')
                                        + ' and an '
                                        + InlineImage('image.pdf')),
                              Section([Heading('A subsection'),
                                       Paragraph('Another paragraph')
                                      ])
                             ]),
                     Section([Heading('Second Section'),
                              List([Paragraph('a list item'),
                                    Paragraph('another list item')
                                   ])
                             ])
                    ])

It is clear that this type of content is best parsed from a structured document format such as reStructuredText or XML. Manually building a document tree is well suited for short, custom documents however.