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 Language: the code of one of the supported languages

Default: EN (English)

strings

Strings to override standard element names

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

Default: none

stylesheet

The stylesheet to use for styling document elements

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

Default: sphinx (= rinoh.stylesheets.sphinx)

parts

The parts making up this document

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

Default: (empty list)

Configuration

alias of rinoh.template.DocumentTemplateConfiguration

ConfigurationFile

alias of rinoh.template.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, source=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 rinoh.template.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 NumberFormat: none, number, symbol, lowercase character, uppercase character, lowercase roman, uppercase roman

Default: number

end_at_page

The type of page to end this document part on

Accepts PageType: left, right, any

Default: any

drop_if_empty

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

Accepts Bool: true or false

Default: true

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 Bool: true or false

Default: false

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 (inherited from DocumentPartTemplate)

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

Default: number

end_at_page

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

Accepts PageType: left, right, any

Default: any

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

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

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

Default: number

end_at_page

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

Accepts PageType: left, right, any

Default: any

drop_if_empty

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

Accepts Bool: true or false

Default: true

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 FlowablesList: Python source code that represents a list of Flowables

Default: []

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 (inherited from DocumentPartTemplate)

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

Default: number

end_at_page

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

Accepts PageType: left, right, any

Default: any

drop_if_empty

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

Accepts Bool: true or false

Default: true

Page Templates

The document templates make use of page templates:

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

header_footer_distance

Distance of the header and footer to the content area

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

Default: 14pt

columns

The number of columns for the body text

Accepts Integer: a natural number (positive integer)

Default: 1

column_spacing

The spacing between columns

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

Default: 1cm

header_text

The text to place in the page header

Accepts StyledText: 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}'

footer_text

The text to place in the page footer

Accepts StyledText: 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}'

chapter_header_text

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

Accepts StyledText: 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)

chapter_footer_text

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

Accepts StyledText: 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)

chapter_title_flowables

Generator that yields the flowables to represent the chapter title

Accepts FlowablesList: Python source code that represents a list of Flowables

Default: none

chapter_title_height

The height of the container holding the chapter title

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

Default: 150pt

page_size

The format of the pages in the document (inherited from PageTemplateBase)

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

Default: A4

page_orientation

The orientation of pages in the document (inherited from PageTemplateBase)

Accepts PageOrientation: portrait, landscape

Default: portrait

left_margin

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

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

Default: 3cm

right_margin

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

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

Default: 3cm

top_margin

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

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

Default: 3cm

bottom_margin

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

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

Default: 3cm

background

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

Accepts BackgroundImage: 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

after_break_background

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

Accepts BackgroundImage: 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

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

show_date

Show or hide the document’s date

Accepts Bool: true or false

Default: true

show_author

Show or hide the document’s author

Accepts Bool: true or false

Default: true

extra

Extra text to include on the title page below the title

Accepts StyledText: 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)

page_size

The format of the pages in the document (inherited from PageTemplateBase)

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

Default: A4

page_orientation

The orientation of pages in the document (inherited from PageTemplateBase)

Accepts PageOrientation: portrait, landscape

Default: portrait

left_margin

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

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

Default: 3cm

right_margin

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

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

Default: 3cm

top_margin

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

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

Default: 3cm

bottom_margin

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

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

Default: 3cm

background

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

Accepts BackgroundImage: 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

after_break_background

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

Accepts BackgroundImage: 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

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 Paper: the name of a predefined paper format or <width> * <height> where width and height are Dimensions

Default: A4

page_orientation

The orientation of pages in the document

Accepts PageOrientation: portrait, landscape

Default: portrait

left_margin

The margin size on the left of the page

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

Default: 3cm

right_margin

The margin size on the right of the page

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

Default: 3cm

top_margin

The margin size at the top of the page

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

Default: 3cm

bottom_margin

The margin size at the bottom of the page

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

Default: 3cm

background

An image to place in the background of the page

Accepts BackgroundImage: 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

after_break_background

An image to place in the background after a page break

Accepts BackgroundImage: 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