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 languagesDefault:
EN
(English)
- strings¶
Strings to override standard element names
Accepts
Strings
: strings need to be entered in INI in a section named ‘STRINGS’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 namesDefault: (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
Document Parts¶
- class rinoh.template.DocumentPart(template, document, flowables, last_number_format)¶
Part of a document.
- Parameters:¶
- configuration_class¶
alias of
DocumentPartTemplate
- add_page(page)¶
Append page (
Page
) to thisDocumentPart
.
-
new_page(page_number, chain, new_chapter, sideways=
False
)¶ Called by
render()
with theChain`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
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
orfalse
Default:
false
(overridesDocumentPartTemplate
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 theDocumentTemplate
.- 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
orfalse
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 ofFlowable
sDefault:
[]
- 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
orfalse
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)}'
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>
wherewidth
andheight
areDimension
sDefault:
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 displayedDefault:
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 displayedDefault:
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)
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 ofFlowable
sDefault:
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)}'
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>
wherewidth
andheight
areDimension
sDefault:
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 displayedDefault:
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 displayedDefault:
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>
wherewidth
andheight
areDimension
sDefault:
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 displayedDefault:
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 displayedDefault:
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>
wherewidth
andheight
areDimension
sDefault:
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 displayedDefault:
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 displayedDefault:
none
- sideways¶
Rotate sideways pages to the left or right
Accepts
Sideways
:left
,right
Default:
right