Sphinx Builder

rinoh.frontend.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:

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'),
]
rinoh_targets

Limits rendering to the specified set of targets. This variable accepts either a list of strings or a string containing comma-separated values. The target names should match those set in rinoh_documents.

To render only the ‘manual’ target, you can set the following in conf.py:

rinoh_targets = ['manual']

The same can be achieved from the command line using the by using the string form with sphinx-build -D:

spinx-build -b rinoh -D rinoh_targets="manual" source build

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

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.