Templates (rinoh.template)

Documents

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=None

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 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, 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=None

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, last_number_format)

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, chain, new_chapter, sideways=False)

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_prefix

Text to place in front ofthe page number.

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_number_format

The format for page numbers in this document part.

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

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

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

Accepts Bool: true or false

Default: false (overrides DocumentPartTemplate default)

page_number_prefix

Text to place in front ofthe page number. (inherited from DocumentPartTemplate)

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_number_format

The format for page numbers in this document part. (inherited from DocumentPartTemplate)

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

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_prefix

Text to place in front ofthe page number. (inherited from DocumentPartTemplate)

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_number_format

The format for page numbers in this document part. (inherited from DocumentPartTemplate)

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

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_prefix

Text to place in front ofthe page number. (inherited from DocumentPartTemplate)

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_number_format

The format for page numbers in this document part. (inherited from DocumentPartTemplate)

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

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.BodyPageTemplateBase(base=None, **attributes)

Distance of the header and footer to the content area

Accepts Dimension: a numeric value followed by a unit (pt, in, pc, mm, cm, %, /2, /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, %, /2, /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(1)}' ' ' '{SECTION_TITLE(1)}'

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}'

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, %, /2, /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, %, /2, /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, %, /2, /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, %, /2, /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

sideways

Rotate sideways pages to the left or right (inherited from PageTemplateBase)

Accepts Sideways: left, right

Default: right

class rinoh.template.BodyPageTemplate(base=None, **attributes)
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, %, /2, /4)

Default: 150pt

Distance of the header and footer to the content area (inherited from BodyPageTemplateBase)

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

Default: 14pt

columns

The number of columns for the body text (inherited from BodyPageTemplateBase)

Accepts Integer: a natural number (positive integer)

Default: 1

column_spacing

The spacing between columns (inherited from BodyPageTemplateBase)

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

Default: 1cm

header_text

The text to place in the page header (inherited from BodyPageTemplateBase)

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(1)}' ' ' '{SECTION_TITLE(1)}'

footer_text

The text to place in the page footer (inherited from BodyPageTemplateBase)

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}'

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, %, /2, /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, %, /2, /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, %, /2, /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, %, /2, /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

sideways

Rotate sideways pages to the left or right (inherited from PageTemplateBase)

Accepts Sideways: left, right

Default: right

class rinoh.template.TitlePageTemplate(base=None, **attributes)
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, %, /2, /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, %, /2, /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, %, /2, /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, %, /2, /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

sideways

Rotate sideways pages to the left or right (inherited from PageTemplateBase)

Accepts Sideways: left, right

Default: right

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, %, /2, /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, %, /2, /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, %, /2, /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, %, /2, /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

sideways

Rotate sideways pages to the left or right

Accepts Sideways: left, right

Default: right