How to use rst2pdf

1.1 Related Reading

As well as the rst2pdf-specific features described in this manual, you many also find it useful to refer to the ReStructuredText manual and information about its directives:

• A ReStructureText Primer: https://docutils.sourceforge.io/docs/user/rst/quickstart.html

• Quick ReStructuredText: https://docutils.sourceforge.io/docs/user/rst/quickref.html

• ReStructuredText Specification: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html

• ReStructuredText Directives: https://docutils.sourceforge.io/docs/ref/rst/directives.html

2.1 General Options

2.2 File and Configuration

2.3 Styling Options

2.4 PDF Options

2.5 Formatting Options

2.6 Miscellaneous Options

3.1 Configuration Options

The table below provides detailed descriptions of the available configuration options.

3.2 Example Configuration File

Here's an example configuration file showing the expected format:

# This is an example config file. Modify and place in ~/.rst2pdf/config

[general]
stylesheets="fruity.json,a4paper.json,verasans.json"

# Folders to search for stylesheets.
stylesheet_path="~/styles:/usr/share/styles"

# Language to be used for hyphenation support
language="en_US"

5.1 Inline

You can insert images in the middle of your text like this:

This |biohazard| means you have to run.

.. |biohazard| image:: assets/biohazard.png

This means you have to run.

5.2 Supported Image Types

For raster images, rst2pdf supports anything PIL (The Python Imaging Library) supports. The exact list of supported formats varies according to your PIL version and system.

For SVG support, you need to install svglib.

Some features will not work when using these images. For example, gradients will not display, and text may cause problems depending on font availability.

If you can choose between raster and vectorial images, for non-photographic images, vector files are usually smaller and look better, specially when printed.

5.3 Image Size

PDFs are meant to reflect paper. A PDF has a specific size in centimeters or inches.

Images usually are measured in pixels, which are meaningless in a PDF. To convert between pixels and inches or centimeters, we use a DPI (dots-per-inch) value.

For example, 300 pixels, with a 300DPI, are exactly one inch. 300 pixels at 100DPI are 3 inches.

For that reason, to achieve a nice layout of the page, it's usually a good idea to specify the size of your images in those units, or as a percentage of the available width and you can ignore all this DPI nonsense ;-)

The rst2pdf default is 300DPI, but you can change it using the --default-dpi option or the default_dpi setting in the config file.

Examples of images with specified sizes:

.. image:: home.png
   :width: 3in

.. image:: home.png
   :width: 80%

.. image:: home.png
   :width: 7cm

The valid units you can use are: em, ex, px, in, cm, mm, pt, pc, %, "".

• px: Pixels. If you specify the size using this unit, rst2pdf will convert it to inches using the default DPI explained above.

• No unit. If you just use a number, it will be considered as pixels. (IMPORTANT: this used to default to points. It was changed to be more compatible with rst2html)

• em: This is the same as your base style's font size. By default: 10 points.

• ex: rst2pdf will use the same broken definition as IE: em/2. In truth this should be the height of the lower-case x character in your base style.

• in: Inches (1 inch = 2.54 cm).

• cm: centimeters (1cm = 0.39 inches)

• mm: millimeters (10mm = 1cm)

• pt: 1/72 inch

• pc: 1/6 inch

• %: percentage of available width in the frame. Setting a percentage as a height does not work and probably never will.

If you don't specify a size at all, rst2pdf will do its best to figure out what it should do:

Since there is no specified size, rst2pdf will try to convert the image's pixel size to inches using the DPI information available in the image itself. You can set that value using most image editors. For example, using Gimp, it's in the Image -> Print Size menu.

So, if your image is 6000 pixels wide, and is set to 1200DPI, it will be 5 inches wide.

If your image doesn't have a DPI property set, and doesn't have it's desired size specified, rst2pdf will arbitrarily decide it should use 300DPI (or whatever you choose with the --default-dpi option).

6.1 Applying Styles

rst2pdf applies a default set of styles to the document. This default set can be viewed using rst2pdf --print-stylesheet which prints outh rst2pdf/styles/styles.yaml.

Each subsequent style within each style sheet file specified the --stylesheets CLI parameter is then registered in the the list of known styles known to rst2pdf. If the name of the style is already known, then the attributes specified in the style are applied "on top" of the already registered style.

rst2pdf will then resolve the parent style, which is why the order of inclusion matters per-style-name, not globally. That is, if you set the color of bodytext first in a file and then set the color of normal in a subsequent file, then the color you have set for bodytext will be the color used for paragraphs (unless overridden by a class directive. Further information on cereating stylesheet files is available in Creating Stylesheets.

You can style paragraphs with a style using the class directive:

.. class:: special

This paragraph is special.

This one is not.

Multiple styles can be listed and are applied in order where properties in the right hand styles override those to the left:

.. class:: special bluetext redtext

    This paragraph is special and is red.

This one is not.

Or inline styles using custom interpreted roles:

.. role:: redtext

I like color :redtext:`red`.

For more information about this, please check the rST docs, and for style information check the section in this manual on inline styles.

6.2 Headers and Footers

rST supports headers and footers, using the header and footer directive:

.. header::

   This will be at the top of every page.

Often, you may want to put a page number there, or a section name.The following magic tokens will be replaced (More may be added as rst2pdf evolves):

###Page###

Replaced by the current page number.

###Title###

Replaced by the document title

###Section###

Replaced by the current section title

###SectNum###

Replaced by the current section number. Important: You must use the sectnum directive for this to work.

###Total###

Replaced by the total number of pages in the document. Keep in mind that this is the real number of pages, not the displayed number, so if you play with page counters this number will probably be wrong.

Headers and footers are visible by default but they can be disabled by specific Page Templates for example, cover pages. You can also set headers and footers via command line options or the configuration file.

If you want to do things like "put the page number on the out side of the page, check The oddeven directive

6.3 Footnotes

Currently rst2pdf doesn't support real footnotes, and converts them to endnotes. There is a real complicated technical reason for this: I can't figure out a clean way to do it right.

You can get the same behaviour as with rst2html by specifying --inline-footnotes, and then the footnotes will appear where you put them (in other words, not footnotes, but "in-the-middle-of-text-notes" or just plain notes.)

7.1 Using Stylesheets

Specify a stylesheet to use with -s:

rst2pdf mydoc.rst -s mystyles

Often it makes sense to specify multiple stylesheets, for example to set the page size, the main styles, and some syntax highlighting. In that case, use comma-separated values:

rst2pdf mydoc.rst -s a4,mystyles,murphy

Order does matter: rst2pdf applies its own stylesheet first and then the list in given in order, so the last stylesheet in the list will take precedence over the ones that went before.

Styles will always be searched in these places, in order:

• What you specify using --stylesheet_path

• The option stylesheet_path in the config file

• The current folder

• ~/.rst2pdf/styles

• The styles folder within rst2pdf's installation folder.

7.2 Included StyleSheets

To make some of the more common adjustments easier, rst2pdf includes a collection of stylesheets you can use:

Font styles

These stylesheets modify your font settings.

• serif uses the PDF serif font (Times) instead of the default Sans Serif (Arial)

• freetype-sans uses your system's default TrueType Sans Serif font

• freetype-serif uses your system's default TrueType Serif font

• twelvepoint makes the base font 12pt (default is 10pt)

• tenpoint makes the base font 10pt

• eightpoint makes the base font 8pt

Page layout styles

These stylesheets modify your page layout.

• twocolumn uses the twoColumn layout as the initial page layout.

• double-sided adds a gutter margin (margin at the "in side" of the pages)

Page size styles

Stylesheets that change the paper size.

The usual standard paper sizes are supported: A0, A1, A2, A3, A4 (default), A5, A6, B0, B1, B2, B3, B4, B5, B6, Letter, Legal, 11x17

The name of the stylesheet is lowercase.

Code block styles

See Syntax Highlighting

So, if you want to have a two-column, legal size, serif document with code in murphy style:

rst2pdf mydoc.txt -s twocolumn,serif,murphy,legal

7.3 Default Stylesheet

You can make rst2pdf print the default stylesheet:

rst2pdf --print-stylesheet

This makes an excellent starting point for creating a stylesheet. The default one is always included by default, so only the values that should be changed need to be included in the new stylesheet.

7.4 Migrating Stylesheet Format

Historically, (version 0.98 and earlier) rst2pdf had support for JSON and RSON stylesheets. Those stylesheets should still work if you are still using them but a warning will be produced:

[WARNING] styles.py:617 Stylesheet "./example.style" in outdated format, recommend converting to YAML

To update your stylesheet, use the rst2pdf.style2yaml utility:

python3 -m rst2pdf.style2yaml example.style

The command also accepts a list of paths, or wildcards, and by default will output the new stylesheet(s) to stdout. To write them to files instead, use the --save flag with the command above.

7.5 Migrating to the New Default Stylesheet

Historically (version 0.98 and earlier), rst2pdf used a different default style sheet. The updated default style file provide a more modern look to rst2pdf documents. To do this, it updates various spacing, margins and fonts. It also updates page template and font alias names and so you will need to make adjustments to derived style files.

Until you make these adjustments, you can use the historical default style sheet using by adding the rst2pdf-0-9 style using the -s command line switch. For example:

rst2pdf mydoc.rst -s rst2pdf-0-9,mystyle.yaml

8.1 Styles in Detail

At the top level there is a bit of an outlier: linkColor. You can specify any color name or a hex value:

linkColor: #330099

Most of the other elements for colours and formatting are in the styles section.

There are particular styles which have great effect, they are base, normal and bodytext.

Here's an example, the twelvepoint stylesheet:

styles:
  base:
    fontSize: 12

Since all other styles inherit base, changing the fontSize changes the fontSize for everything in your document.

The normal style is meant for most elements, so usually it's the same as changing base.

The bodytext style is for elements that form paragraphs. So, for example, you can set your document to be left-aligned like this:

styles:
 - bodytext:
      alignment: TA_LEFT

There are elements, however, that don't inherit from bodytext, for example headings and the styles used in the table of contents. Those are elements that are not real paragraphs, so they should not follow the indentation and spacing you use for your document's main content.

The heading style is inherited by all sorts of titles: section titles, topic titles, admonition titles, etc.

If your document requires a style that is not defined in your stylesheet, it will print a warning and use bodytext instead.

Also, the order of the styles is important: if styleA is the parent of styleB, styleA should be earlier in the stylesheet.

8.2 Style Elements

Within the styles element, it is possible to configure each element type. The following section lays out the known options and examples of how to use them. (This list is known to be incomplete, we're working on it and accept any additions you have).

parent

Each style property can inherit from another, for example the code style inherits from the literal style which sets the font used for fixed-width text throughout the document.

Example:

code:
  parent: literal

fontName

The name of the font to use for this type of element. It can be either the name of a font on your system, or one of the aliased fonts. The default is Helvetica as shown in the example here.

Example:

fontName: Helvetica

See also:

• Font Alias

• Fonts

fontSize

Use either a number (meaning point size) or a percentage. The default size for bodytext is 10.

Example:

fontSize: 150%

leftIndent and rightIndent

Example:

leftIndent: 0
rightIndent: 0

firstLineIndent

Example:

firstLineIndent: 0

alignment

The paragraph justification of the text. The values TA_LEFT and TA_RIGHT can be used.

Example:

alignment: TA_LEFT

spaceBefore and spaceAfter

The amount of vertical space included before or after an element. Especially useful when working with bullet-list and bullet-list-item elements.

Example:

spaceBefore: 4
spaceAfter: 8

bullet -related styles

The bullets can be complex to style, but there are some tricks that might help. The vertical space before and after the list and item elements are controlled by the spaceBefore and spaceAfter properties. Also these lists are tables so those styles also apply.

Example:

bulletFontName: Helvetica
bulletFontSize: 10
bulletText: "\u2022"
bulletIndent: 0

See also:

• Table Styles

textColor

Use either a color name, or a hex value including the # character at the start.

Example:

textColor: black

backColor

Use either the value None, a color name, or a hex value including the # character at the start. Sets the background color of the element.

Example:

backColor: beige

wordWrap

Can be set to None.

Example:

wordWrap: None

border -related styles

Setting and styling the border for an element. The example is from the default code block style.

Example:

borderColor: darkgray
borderPadding: 6
borderWidth: 0.5
borderRadius: None

allowWidows and allowOrphans

These directives are passed to ReportLab if they are present. Currently only implemented for paragraph styles.

Example:

allowWidows: 5
allowOrphans: 4

See also:

• Widows and Orphans

margin -related styles

This sets the margins of the element. On the pageSetup itself, you can use margin-gutter. That's the margin in the center of a two-page spread. This value is added to the left margin of odd pages and the right margin of even pages, adding (or removing, if it's negative) space "in the middle" of opposing pages. If you intend to bound a printed copy, you may need extra space there. OTOH, if you will display it on-screen on a two-page format (common in many PDF readers, nice for ebooks), a negative value may be pleasant.

Example:

margin-top: 2cm
margin-bottom: 2cm
margin-left: 2cm
margin-right: 2cm
margin-gutter: 0cm

styles:
  item-list
      parent: bodytext
      spaceBefore: 0
      commands:
      - - VALIGN: [[0, 0], [-1, -1]]
          - TOP
      - - RIGHTPADDING: [[0, 0], [1, -1], 0]
      colWidths:
      - 20pt
  - bullet-list
      parent: bodytext
      spaceBefore: 0
      commands:
      - - VALIGN: [[0, 0], [-1, -1]]
          - TOP
      - - RIGHTPADDING: [[0, 0], [1, -1], 0]
      colWidths:
      - '20'

bullet-list-item:
  parent: bodytext
  spaceBefore: 20

8.3 Page Layout

There are some layouts available as standard stylesheets, but it is likely that you will also want to describe your own templates.

pageSetup:
  size: A4
  width:
  height:
  margin-top: 2cm
  margin-bottom: 2cm
  margin-left: 2cm
  margin-right: 2cm
  spacing-header: 5mm
  spacing-footer: 5mm
  margin-gutter: 0cm

pageSetup:
    size: null
    width: 32cm
    height: 18cm

pageTemplates:
  coverPage:
    frames:
    - [0cm, 0cm, 100%, 100%]
    showHeader: false
    showFooter: false
  oneColumn:
    frames:
    - [0cm, 0cm, 100%, 100%]
  twoColumn:
    frames:
    - [0cm, 0cm, 49%, 100%]
    - [51%, 0cm, 49%, 100%]

[ left position, bottom position, width, height, left padding, bottom padding, right padding, top padding]

["0cm", "0cm", "49%", "100%"]

["0cm", "66.66%", "100%", "33.34%"]

pageSetup:
  firstTemplate: oneColumn

.. raw:: pdf

   PageBreak twoColumn

8.4 Font Alias

This is the fontsAlias element. By default, it uses some of the standard PDF fonts:

fontsAlias:
  fontSerif: Helvetica
  fontSerifBold: Helvetica-Bold
  fontSerifItalic: Helvetica-Oblique
  fontSerifBoldItalic: Helvetica-BoldOblique
  fontMono: Courier

This defines the fonts used in the styles. You can use, for example, Helvetica directly in a style, but if later you want to use another font all through your document, you will have to change it in each style. So, I suggest you use aliases.

More information in the dedicated Fonts section.

8.5 Widows and Orphans

Widow

A paragraph-ending line that falls at the beginning of the following page/column, thus separated from the remainder of the text.

Orphan

A paragraph-opening line that appears by itself at the bottom of a page/column.

rst2pdf has some widow/orphan control. Specifically, here's what's currently implemented:

On ordinary paragraphs, allowWidows and allowOrphans is passed to reportlab, which is supposed to do something about it if they are non-zero. In practice, it doesn't seem to have much effect.

The plan is to change the semantics of those settings, so that they mean the minimum number of lines that can be left alone at the beginning of a page (widows) or at the end (orphans).

Currently, these semantics only work for literal blocks and code blocks.

A literal block::

    This is a literal block.

A code block:

.. code-block:: python

    def x(y):
        print y**2

In future versions this may extend to ordinary paragraphs.

8.6 Table Styles

These are a few extra options in styles that are only used when the style is applied to a table. This happens in two cases:

1. You are using the class directive on a table:

.. class:: thick

+-------+---------+
|   A   |   B     |
+-----------------+

2. It's a style that automatically applies to something that is drawn using a table. Currently these include:

   • Footnotes / endnotes (endnote style)

   • Lists (item-list, bullet-list, option-list and field-list styles)

The options are as follows:

Commands

For a full reference of these, please check the Reportlab User Guide specifically the TableStyle Commands section (section 7.4 in the manual for version 2.3)

Here, however, is a list of the possible commands:

BOX (or OUTLINE)
FONT
FONTNAME (or FACE)
FONTSIZE (or SIZE)
GRID
INNERGRID
LEADING
LINEBELOW
LINEABOVE
LINEBEFORE
LINEAFTER
TEXTCOLOR
ALIGNMENT (or ALIGN)
LEFTPADDING
RIGHTPADDING
BOTTOMPADDING
TOPPADDING
BACKGROUND
ROWBACKGROUNDS
COLBACKGROUNDS
VALIGN

Each takes as argument a couple of coordinates, where (0,0) is top-left, and (-1,-1) is bottom-right, and 0 or more extra arguments.

For example, INNERGRID takes a line width and a color:

[ "INNERGRID", [ 0, 0 ], [ -1, -1 ], 0.25, "black" ],

That would mean "draw all lines inside the table with .25pt black"

colWidths

A list of the column widths you want, in the unit you prefer (default unit is pt).

Example:

"colWidths": ["3cm",null]

If your colWidths has fewer values than columns in your table, the rest are auto-calculated. A column width of null means "guess".

If you don't specify column widths, the table will try to look proportional to the restructured text source.

9.1 File inclusion

You can use the code-block directive with an external file, using the :include: option:

.. code-block:: python
   :include: my_script.py

This will give a warning if my_script.py doesn't exist or can't be opened.

10.1 Standard PDF Fonts

The standard PDF fonts are always available, here is the list:

• Times_Roman

• Times-Bold

• Times-Italic

• Times-Bold-Italic

• Helvetica

• Helvetica_Bold

• Helvetica-Oblique

• Helvetica-Bold-Oblique

• Courier

• Courier-Bold

• Courier-Oblique

• Courier-Bold-Oblique

• Symbol

• Zapf-Dingbats

10.2 Font Embedding

There are thousands of excellent free True Type and Type 1 fonts available on the web, and you can use many of them in your documents by declaring them in your stylesheet.

normal:
  fontName: fonty

/usr/share/texmf-dist/fonts/type1/urw/palatino/uplb8a.pfb
/usr/share/texmf-dist/fonts/type1/urw/palatino/uplbi8a.pfb
/usr/share/texmf-dist/fonts/type1/urw/palatino/uplr8a.pfb
/usr/share/texmf-dist/fonts/type1/urw/palatino/uplri8a.pfb
/usr/share/texmf-dist/fonts/afm/urw/palatino/uplb8a.afm
/usr/share/texmf-dist/fonts/afm/urw/palatino/uplbi8a.afm
/usr/share/texmf-dist/fonts/afm/urw/palatino/uplr8a.afm
/usr/share/texmf-dist/fonts/afm/urw/palatino/uplri8a.afm

rst2pdf mydoc.txt -s mystyle.style --font-path /usr/share/texmf-dist/fonts

title:
  fontName: URWPalladioL-Bold

'ITC Bookman'            : 'URW Bookman L',
'ITC Avant Garde Gothic' : 'URW Gothic L',
'Palatino'               : 'URW Palladio L',
'New Century Schoolbook' : 'Century Schoolbook L',
'ITC Zapf Chancery'      : 'URW Chancery L'

embeddedFonts: []

embeddedFonts:
  - [Tuffy.ttf, Tuffy_Bold.ttf, Tuffy_Italic.ttf, Tuffy_Bold_Italic.ttf]

embeddedFonts:
  - [Tuffy.ttf, Tuffy.ttf, Tuffy.ttf, Tuffy.ttf]

fontsAlias:
  fontSans: Tuffy
  fontSansBoldfontSansBold: Tuffy_Bold
  fontSansItalic: Tuffy_Italic
  fontSansBoldItalic: Tuffy_Bold_Italic
  fontMono: Courier

heading1:
  parent: normal
  fontName: Tuffy_Bold
  fontSize: 18
  keepWithNext: true
  spaceAfter: 6

11.1 Raw PDF

rst2pdf has a very limited mechanism to pass commands to reportlab, the PDF generation library. You can use the raw directive to insert pagebreaks and spacers (other reportlab flowables may be added if there's interest), and set page transitions.

The syntax is shell-like, here's an example:

One page

.. raw:: pdf

    PageBreak background=images/background.jpg fit-background-mode=scale

Another page. Now some space:

.. raw:: pdf

    Spacer 0,200
    Spacer 0 200

And another paragraph.

The unit used by the spacer by default is points, and using a space or a comma is the same thing in all cases.

11.2 Page Counters

In some documents, you may not want your page counter to start in the first page.

For example, if the first pages are a coverpage and a table of contents, you want page 1 to be where your first section starts.

To do that, you have to use the SetPageCounter command.

Here is a syntax example:

.. raw:: pdf

    SetPageCounter 0 lowerroman

This sets the counter to 0, and makes it display in lower roman characters (i, ii, iii, etc) which is a style often used for the pages before the document proper (for example, TOCs and abstracts).

It can take zero or two arguments.

SetPageCounter

When used with no arguments, it sets the counter to 0, and the style to arabic numerals.

SetPageCounter number style

When used with two arguments, the first argument must be a number, it sets the page counter to that number.

The second number is a style of counter. Valid values are:

• lowerroman: i, ii, iii, iv, v ...

• roman: I, II, III, IV, V ...

• arabic: 1, 2, 3, 4, 5 ...

• loweralpha: a, b, c, d, e ... [Don't use for numbers above 26]

• alpha: A, B, C, D, E ... [Don't use for numbers above 26]

11.3 Page Breaks

There are three kinds of page breaks:

PageBreak

Break to the next page

EvenPageBreak

Break to the next even numbered page

OddPageBreak

Break to the next odd numbered page

Each of them can take an optional argument which is the name of the next page template. For example:

PageBreak twoColumn

In addition, two additional attributes are supported: background and fit-background-mode. These allow setting the background image for this page and how to fit it (One of scale, scale_width or center). For example:

PageBreak mainPage background="images/background.jpg"

or:

PageBreak background=images/background.jpg fit-background-mode=scale

11.4 Frame Breaks

If you want to jump to the next frame in the page (or the next page if the current frame is the last), you can use the FrameBreak command. It takes an optional height in points, and then it only breaks the frame if there is less than that vertical space available.

For example, if you don't want a paragraph to begin if it's less than 50 points from the bottom of the frame:

.. raw:: pdf

   FrameBreak 50

This paragraph is so important that I don't want it at the very bottom of
the page...

11.5 Page Transitions

Page transitions are effects used when you change pages in Presentation or Full Screen mode (depends on the viewer). You can use it when creating a presentation using PDF files.

The syntax is this:

.. raw:: pdf

   Transition effect duration [optional arguments]

The optional arguments are:

direction

Can be 0,90,180 or 270 (top,right,bottom,left)

dimension

Can be H or V

motion

Can be I or O (Inside or Outside)

The effects with their arguments are:

• Split duration direction motion

• Blinds duration dimension

• Box duration motion

• Wipe duration direction

• Dissolve duration

• Glitter duration direction

For example:

.. raw:: pdf

   Transition Glitter 3 90

Uses the Glitter effect, for 3 seconds, at direction 90 degrees (from the right?)

Keep in mind that Transition sets the transition from this page to the next so the natural thing is to use it before a PageBreak:

.. raw:: pdf

   Transition Dissolve 1
   PageBreak

11.6 Text Annotations

Text annotations are meta notes added to a page.

The syntax is this:

.. raw:: pdf

   TextAnnotation "text to add" [optional position]

The optional position is a set of 4 numbers for x_begin, y_begin`, ``x_end and y_end

11.7 Raw HTML

If you have a document that contains raw HTML, and have xhtml2pdf installed, rst2pdf will try to render that HTML inside your document. To enable this, use the --raw-html command line option.