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.
rinoh --format reStructuredText demo.txt
After rendering finishes, you will find
demo.pdf alongside the
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.
To use rinohtype to render Sphinx documents, at a minimum you need to add
'rinoh.frontend.sphinx' to the
extensions list in the Sphinx
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¶
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
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.