Templates (rinoh.template)

Document templates are created by subclassing DocumentTemplate, just like the standard templates shipped with rinohtype.

class rinoh.template.DocumentTemplate(document_tree, configuration=None, backend=None)

Template for documents

Parameters
  • document_tree (DocumentTree) – a tree of the document’s contents

  • configuration (TemplateConfiguration) – configuration for this template

  • backend – the backend used for rendering the document

language

The main language of the document

Accepts: the code of one of the supported languages

Default: EN (English)

Type

Language

strings

Strings to override standard element names

Accepts: strings need to be entered in INI sections named after the StringCollection subclasses

Default: none

Type

Strings

stylesheet

The stylesheet to use for styling document elements

Accepts: the name of an installed style sheet or the filename of a stylesheet file (with the .rts extension)

Default: sphinx (= rinoh.stylesheets.sphinx)

Type

StyleSheet

parts

The parts making up this document

Accepts: a space-separated list of document part template names

Default: (empty list)

Type

PartsList

Configuration

alias of DocumentTemplateConfiguration

ConfigurationFile

alias of DocumentTemplateConfigurationFile

Document templates can be customized by setting values for the configuration attributes defined in a DocumentTemplate subclass in a TemplateConfiguration. An template configuration can be passed as configuration on template instantiation. However, it is better to make use of the document method, however.

class rinoh.template.TemplateConfiguration(name, base=None, template=None, description=None, **options)

Stores a configuration for a DocumentTemplate

Parameters
  • name (str) – a label for this template configuration

  • base (TemplateConfiguration) – the template configuration to extend

  • template (DocumentTemplateMeta or str) – the document template to configure

  • description (str) – a short string describing this style sheet

  • **options – configuration values for the configuration attributes defined by the document template

template = None

The DocumentTemplate subclass to configure

document(document_tree, backend=None)

Create a DocumentTemplate object based on the given document tree and this template configuration

Parameters
  • document_tree (DocumentTree) – tree of the document’s contents

  • backend – the backend to use when rendering the document

class rinoh.template.PartsList(*parts)

Stores the names of the document part templates making up a document

Parameters

*parts (list[str]) – the names of the document parts

Document Parts

class rinoh.template.DocumentPart(template, document, flowables)

Part of a document.

Parameters
  • template (DocumentPartTemplate) – the template that determines the contents and style of this document part

  • document (Document) – the document this part belongs to

  • flowables (list[Flowable]) – the flowables to render in this document part

configuration_class

alias of DocumentPartTemplate

add_page(page)

Append page (Page) to this DocumentPart.

new_page(page_number, new_chapter, **kwargs)

Called by render() with the Chain`s that need more :class:`Container`s. This method should create a new :class:`Page which contains a container associated with chain.

The document part templates which are listed by name in DocumentTemplate.parts are looked up as attributes of the DocumentTemplate subclass. They are instances of DocumentPartTemplate subclasses:

class rinoh.template.DocumentPartTemplate(base=None, **attributes)

A template that produces a document part

The document part is created given a set of flowables, and page templates. The latter are looked up in the TemplateConfiguration where this part template was.

page_number_format

The format for page numbers in this document part. If it is different from the preceding part’s number format, numbering restarts at 1

Accepts: none, number, symbol, lowercase character, uppercase character, lowercase roman, uppercase roman

Default: number

Type

NumberFormat

end_at_page

The type of page to end this document part on

Accepts: left, right, any

Default: any

Type

PageType

drop_if_empty

Exclude this part from the document if it is empty (no flowables)

Accepts: true or false

Default: true

Type

Bool

The following document part templates are used in the standard document templates:

class rinoh.template.TitlePartTemplate(base=None, **attributes)

The title page of a document.

drop_if_empty

Overrides the default set in DocumentPartTemplate

Accepts: true or false

Default: false

Type

Bool

page_number_format

(DocumentPartTemplate) The format for page numbers in this document part. If it is different from the preceding part’s number format, numbering restarts at 1

Accepts: none, number, symbol, lowercase character, uppercase character, lowercase roman, uppercase roman

Default: number

Type

NumberFormat

end_at_page

(DocumentPartTemplate) The type of page to end this document part on

Accepts: left, right, any

Default: any

Type

PageType

class rinoh.template.ContentsPartTemplate(base=None, **attributes)

The body of a document.

Renders all of the content present in the DocumentTree passed to the DocumentTemplate.

page_number_format

(DocumentPartTemplate) The format for page numbers in this document part. If it is different from the preceding part’s number format, numbering restarts at 1

Accepts: none, number, symbol, lowercase character, uppercase character, lowercase roman, uppercase roman

Default: number

Type

NumberFormat

end_at_page

(DocumentPartTemplate) The type of page to end this document part on

Accepts: left, right, any

Default: any

Type

PageType

drop_if_empty

(DocumentPartTemplate) Exclude this part from the document if it is empty (no flowables)

Accepts: true or false

Default: true

Type

Bool

class rinoh.template.FixedDocumentPartTemplate(base=None, **attributes)

A document part template that renders a fixed list of flowables

flowables

The list of flowables to include in this document part

Accepts: Python source code that represents a list of Flowables

Default: []

Type

FlowablesList

page_number_format

(DocumentPartTemplate) The format for page numbers in this document part. If it is different from the preceding part’s number format, numbering restarts at 1

Accepts: none, number, symbol, lowercase character, uppercase character, lowercase roman, uppercase roman

Default: number

Type

NumberFormat

end_at_page

(DocumentPartTemplate) The type of page to end this document part on

Accepts: left, right, any

Default: any

Type

PageType

drop_if_empty

(DocumentPartTemplate) Exclude this part from the document if it is empty (no flowables)

Accepts: true or false

Default: true

Type

Bool

Page Templates

The document templates make use of page templates:

class rinoh.template.PageTemplate(base=None, **attributes)

Distance of the header and footer to the content area

Accepts: a numeric value followed by a unit (pt, in, pc, mm, cm, %, /4)

Default: 14pt

Type

Dimension

columns

The number of columns for the body text

Accepts: a natural number (positive integer)

Default: 1

Type

Integer

column_spacing

The spacing between columns

Accepts: a numeric value followed by a unit (pt, in, pc, mm, cm, %, /4)

Default: 1cm

Type

Dimension

header_text

The text to place in the page header

Accepts: a list of styled text strings, separated by spaces. A styled text string is a quoted string (' or "), optionally followed by a style name enclosed in braces: 'text string' (style name)

Default: '{SECTION_NUMBER}' ' ' '{SECTION_TITLE}'

Type

StyledText

footer_text

The text to place in the page footer

Accepts: a list of styled text strings, separated by spaces. A styled text string is a quoted string (' or "), optionally followed by a style name enclosed in braces: 'text string' (style name)

Default: '\t' '{PAGE_NUMBER}' '/' '{NUMBER_OF_PAGES}'

Type

StyledText

chapter_header_text

The text to place in the header on a page that starts a new chapter

Accepts: a list of styled text strings, separated by spaces. A styled text string is a quoted string (' or "), optionally followed by a style name enclosed in braces: 'text string' (style name)

Default: (no value)

Type

StyledText

The text to place in the footer on a page that starts a new chapter

Accepts: a list of styled text strings, separated by spaces. A styled text string is a quoted string (' or "), optionally followed by a style name enclosed in braces: 'text string' (style name)

Default: (no value)

Type

StyledText

chapter_title_flowables

Generator that yields the flowables to represent the chapter title

Accepts: Python source code that represents a list of Flowables

Default: none

Type

FlowablesList

chapter_title_height

The height of the container holding the chapter title

Accepts: a numeric value followed by a unit (pt, in, pc, mm, cm, %, /4)

Default: 150pt

Type

Dimension

page_size

(PageTemplateBase) The format of the pages in the document

Accepts: the name of a predefined paper format or <width> * <height> where width and height are Dimensions

Default: A4

Type

Paper

page_orientation

(PageTemplateBase) The orientation of pages in the document

Accepts: portrait, landscape

Default: portrait

Type

PageOrientation

left_margin

(PageTemplateBase) The margin size on the left of the page

Accepts: a numeric value followed by a unit (pt, in, pc, mm, cm, %, /4)

Default: 3cm

Type

Dimension

right_margin

(PageTemplateBase) The margin size on the right of the page

Accepts: a numeric value followed by a unit (pt, in, pc, mm, cm, %, /4)

Default: 3cm

Type

Dimension

top_margin

(PageTemplateBase) The margin size at the top of the page

Accepts: a numeric value followed by a unit (pt, in, pc, mm, cm, %, /4)

Default: 3cm

Type

Dimension

bottom_margin

(PageTemplateBase) The margin size at the bottom of the page

Accepts: a numeric value followed by a unit (pt, in, pc, mm, cm, %, /4)

Default: 3cm

Type

Dimension

background

(PageTemplateBase) An image to place in the background of the page

Accepts: filename of an image file enclosed in quotes, optionally followed by space-delimited keyword arguments (<keyword>=<value>) that determine how the image is displayed

Default: none

Type

BackgroundImage

after_break_background

(PageTemplateBase) An image to place in the background after a page break

Accepts: filename of an image file enclosed in quotes, optionally followed by space-delimited keyword arguments (<keyword>=<value>) that determine how the image is displayed

Default: none

Type

BackgroundImage

class rinoh.template.TitlePageTemplate(base=None, **attributes)
show_date

Show or hide the document’s date

Accepts: true or false

Default: true

Type

Bool

show_author

Show or hide the document’s author

Accepts: true or false

Default: true

Type

Bool

extra

Extra text to include on the title page below the title

Accepts: a list of styled text strings, separated by spaces. A styled text string is a quoted string (' or "), optionally followed by a style name enclosed in braces: 'text string' (style name)

Default: (no value)

Type

StyledText

page_size

(PageTemplateBase) The format of the pages in the document

Accepts: the name of a predefined paper format or <width> * <height> where width and height are Dimensions

Default: A4

Type

Paper

page_orientation

(PageTemplateBase) The orientation of pages in the document

Accepts: portrait, landscape

Default: portrait

Type

PageOrientation

left_margin

(PageTemplateBase) The margin size on the left of the page

Accepts: a numeric value followed by a unit (pt, in, pc, mm, cm, %, /4)

Default: 3cm

Type

Dimension

right_margin

(PageTemplateBase) The margin size on the right of the page

Accepts: a numeric value followed by a unit (pt, in, pc, mm, cm, %, /4)

Default: 3cm

Type

Dimension

top_margin

(PageTemplateBase) The margin size at the top of the page

Accepts: a numeric value followed by a unit (pt, in, pc, mm, cm, %, /4)

Default: 3cm

Type

Dimension

bottom_margin

(PageTemplateBase) The margin size at the bottom of the page

Accepts: a numeric value followed by a unit (pt, in, pc, mm, cm, %, /4)

Default: 3cm

Type

Dimension

background

(PageTemplateBase) An image to place in the background of the page

Accepts: filename of an image file enclosed in quotes, optionally followed by space-delimited keyword arguments (<keyword>=<value>) that determine how the image is displayed

Default: none

Type

BackgroundImage

after_break_background

(PageTemplateBase) An image to place in the background after a page break

Accepts: filename of an image file enclosed in quotes, optionally followed by space-delimited keyword arguments (<keyword>=<value>) that determine how the image is displayed

Default: none

Type

BackgroundImage

The base class for these collects the common options:

class rinoh.template.PageTemplateBase(base=None, **attributes)
page_size

The format of the pages in the document

Accepts: the name of a predefined paper format or <width> * <height> where width and height are Dimensions

Default: A4

Type

Paper

page_orientation

The orientation of pages in the document

Accepts: portrait, landscape

Default: portrait

Type

PageOrientation

left_margin

The margin size on the left of the page

Accepts: a numeric value followed by a unit (pt, in, pc, mm, cm, %, /4)

Default: 3cm

Type

Dimension

right_margin

The margin size on the right of the page

Accepts: a numeric value followed by a unit (pt, in, pc, mm, cm, %, /4)

Default: 3cm

Type

Dimension

top_margin

The margin size at the top of the page

Accepts: a numeric value followed by a unit (pt, in, pc, mm, cm, %, /4)

Default: 3cm

Type

Dimension

bottom_margin

The margin size at the bottom of the page

Accepts: a numeric value followed by a unit (pt, in, pc, mm, cm, %, /4)

Default: 3cm

Type

Dimension

background

An image to place in the background of the page

Accepts: filename of an image file enclosed in quotes, optionally followed by space-delimited keyword arguments (<keyword>=<value>) that determine how the image is displayed

Default: none

Type

BackgroundImage

after_break_background

An image to place in the background after a page break

Accepts: filename of an image file enclosed in quotes, optionally followed by space-delimited keyword arguments (<keyword>=<value>) that determine how the image is displayed

Default: none

Type

BackgroundImage