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.
Installing rinohtype places the rinoh script in the
This can be used to render structured documents such as demo.txt
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.
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
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 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 in later sections.
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.