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¶

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

rinoh_documents = [dict(doc='index',        # top-level file (index.rst)
                        target='manual')]   # output file (manual.pdf)

The dictionary accepts optional keys in addition to the required doc and target keys. See Sphinx Builder for details.

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

sphinx-build -b rinoh . _build/rinoh

Note that, just like the rinoh command line tool, the Sphinx builder requires two rendering passes.

High-level PDF Library¶

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 in later sections.

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.