Document Templates¶

When it is not possible to achieve a particular document style using one of the existing templates and a custom template configuration, you can create a new template. A new template is programmed in Python and therefor it is required that you are familiar with Python, or at least with general object-oriented programming.

Subclassing a Template¶

If you need to customize a template beyond what is possible by configuration, you can subclass a template class and override document part and page templates with custom templates. The following example subclasses Article.

from rinoh.attribute import OverrideDefault
from rinoh.template import DocumentPartTemplate, BodyPageTemplate
from rinoh.templates import Article


class BibliographyPartTemplate(DocumentPartTemplate):
    ...


class MyArticle(Article):
    parts = OverrideDefault(['contents', 'bibliography'])

    # default document part templates
    bibliography = BibliographyPartTemplate()

    # default page templates
    bibliography_page = BodyPageTemplate(base='page')

MyArticle extends the Article template, adding the extra bibliography document part, along with the page template bibliography_page. The new document part is included in parts.

Creating a Custom Template¶

A new template can be created from scratch by subclassing DocumentTemplate, defining all document parts, their templates and page templates.

The Article and Book templates are examples of templates that inherit directly from DocumentTemplate. We will briefly discuss the article template, the simpler of the two. The Article template overrides the default style sheet and lists a single document part named contents in the parts attribute and provided a template for it are provided along with page templates:

class Article(DocumentTemplate):
    stylesheet = OverrideDefault(sphinx_article)
    abstract_location = Option(AbstractLocation, 'title',
                               'Where to place the abstract')

    parts = OverrideDefault(['contents'])

    # default document part templates
    contents = ArticleContentsPartTemplate(page_number_format='number')

    # default page templates
    page = ArticleBodyPageTemplate(page_size=Var('paper_size'),
                                   left_margin=1.2*CM,
                                   right_margin=1.2*CM,
                                   top_margin=1.8*CM,
                                   bottom_margin=1.6*CM,
                                   header_footer_distance=2*PT)
    contents_page = ArticleBodyPageTemplate(base='page')

Have a look at the Book template source code for an example of a slightly more complex template that defines separate templates for left and right pages.