Sphinx Builder¶

rinoh.frontent.sphinx is a Sphinx extension module. It provides a Sphinx builder with the name rinoh. The builder recognizes the following conf.py options. Of these, only rinoh_documents (or latex_documents) is required.

rinoh_documents¶

Determines which PDF documents to build. Its format is a list of dictionaries, one for each document to be generated. The supported keys for these dictionaries are listed below. Two of them are required:

doc (required): String that specifies the name of the master document (typically index).
target (required): The name of the target PDF file without the extension.

The following keys allow overriding the content included on the document’s title page and page headers/footers (depending on the template and its configuration). The values for text content can be plain text or StyledText.

logo (no default): Path (absolute or relative to the location of the conf.py file) to an image file, typically included on the title page.
title (default: “project documentation”): The title of the document.
subtitle (default: “Release release”): Subtitle of the document.
author (default: “author”): The document’s author.
date (default: determined from today and today_fmt): The document (build) date.

The remaining keys control what is included in the document and the document template (configuration) to use.

toctree_only (default: False)

Must be True or False. If true, the document itself is not included in the output, only the documents referenced by it via TOC trees.

domain_indices (default: True)

If true, generate domain-specific indices in addition to the general index. It is equivalent to the html_domain_indices and latex_domain_indices configuration variables.

template (default: Book)

Determines the template used to render the document. It takes:

the filename of a template configuration file,
a TemplateConfiguration instance,
the name of an installed template (see rinoh --list-templates), or
a DocumentTemplate subclass

rinoh_documents will also accept other keys than those listed above. These items will be available as document metadata and can be used in a custom document template.

Example:

rinoh_documents = [
    dict(doc='index', target='manual', toctree_only=False,
         template='manual.rtt', logo='logo.pdf'),
    dict(doc='ref', target='reference', title='Reference Manual',
         template='reference.rtt', stamp='DRAFT'),
]

Legacy Configuration Variables¶

The configuration variables below are no longer supported. Instead, their functionality can now be configured per document in rinoh_documents.

rinoh_template¶: This configuration variable is no longer supported since the document template can be specified in rinoh_documents entries.

rinoh_stylesheet¶

This configuration variable is no longer supported since it is not obvious which style sheet will be used when the template configuration also specifies a style sheet. Please specify the style sheet to use in your template configuration file:

[TEMPLATE_CONFIGURATION]
name = My Book
template = book
stylesheet = my_stylesheet.rts

rinoh_paper_size¶

This configuration variable is no longer supported since it was not obvious which paper size was being used when the template configuration (rinoh_template) also specified a paper size. Please specify the paper_size to use in your template configuration file:

[TEMPLATE_CONFIGURATION]
name = My Book
template = book

[VARIABLES]
paper_size = A5

rinoh_logo¶: This configuration variable is no longer supported since the logo can be specified in the rinoh_documents entries.

rinoh_domain_indices¶: This configuration variable is no longer supported since the domain_indices can be specified in the rinoh_documents entries.

rinoh_metadata¶: This configuration variable is no longer supported. Metadata entries can now be added to rinoh_documents entries.