rst2pdf

https://rst2pdf.org/
Admin
rst2pdf is an open-source tool that creates professional-looking PDF documents from ReStructured...
Tokens:18,081
Snippets:281
Trust Score:8.3
Update:2 months ago
Show doc for...
Tokens:
Raw
### Basic YAML Stylesheet Structure

Source: https://rst2pdf.org/_sources/manual.rst.txt

A minimal example showing how to define page setup, font aliases, and base styles.

```yaml
pageSetup:
  size: A5
fontsAlias:
  fontSerif: Times-Roman
styles:
  normal:
    fontSize: 14
```

--------------------------------

### List Type 1 font files

Source: https://rst2pdf.org/_sources/manual.rst.txt

Example file structure for a Type 1 font installation.

```text
/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
```

--------------------------------

### Configure Page Setup

Source: https://rst2pdf.org/_sources/manual.rst.txt

Setting the initial page template in the stylesheet.

```yaml
pageSetup:
    firstTemplate: oneColumn
```

--------------------------------

### Install rst2pdf from source

Source: https://rst2pdf.org/index.html

Clones the repository and installs the package with all optional dependencies from the local source directory.

```bash
git clone https://github.com/rst2pdf/rst2pdf
cd rst2pdf
pipx install .[aafiguresupport,mathsupport,plantumlsupport,rawhtmlsupport,sphinx,svgsupport]
```

--------------------------------

### Python Console and Traceback Examples

Source: https://rst2pdf.org/_sources/manual.rst.txt

Examples of rendering Python console sessions and tracebacks.

```rst
.. code-block:: pycon

    >>> my_string="python is great"
    >>> my_string.find('great')
    10
    >>> my_string.startswith('py')
    True
```

```rst
.. code-block:: pytb

    Traceback (most recent call last):
        File "error.py", line 9, in ?
        main()
        File "error.py", line 6, in main
        print call_error()
        File "error.py", line 2, in call_error
        r = 1/0
    ZeroDivisionError: integer division or modulo by zero
    Exit 1
```

--------------------------------

### Install PDF Presenter Console on Ubuntu

Source: https://rst2pdf.org/index.html

Command to install the PDF Presenter Console utility on Linux systems using the apt package manager.

```bash
apt-get install pdf-presenter-console
```

--------------------------------

### Python traceback example

Source: https://rst2pdf.org/manual.html

Example of a Python traceback output.

```text
Traceback (most recent call last):
    File "error.py", line 9, in ?
    main()
    File "error.py", line 6, in main
    print call_error()
    File "error.py", line 2, in call_error
    r = 1/0
ZeroDivisionError: integer division or modulo by zero
Exit 1
```

--------------------------------

### Install rst2pdf with optional dependencies

Source: https://rst2pdf.org/index.html

Installs rst2pdf along with support for features like aafigure, math, plantuml, rawhtml, sphinx, and svg.

```bash
pipx install rst2pdf[aafiguresupport,mathsupport,plantumlsupport,rawhtmlsupport,sphinx,svgsupport]
```

--------------------------------

### Configure Page Setup

Source: https://rst2pdf.org/manual.html

Defines the default page layout including dimensions and margins.

```yaml
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

```

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

```

--------------------------------

### Default Page Setup Configuration

Source: https://rst2pdf.org/_sources/manual.rst.txt

Standard page layout configuration including margins and header/footer spacing.

```yaml
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
```

--------------------------------

### Install rst2pdf via pipx

Source: https://rst2pdf.org/index.html

Installs the latest stable release of rst2pdf using pipx.

```bash
pipx install rst2pdf
```

--------------------------------

### Example Configuration File

Source: https://rst2pdf.org/_sources/manual.rst.txt

An INI-style configuration file for rst2pdf. Place this in ~/.rst2pdf/config to override system defaults.

```ini
# 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"
```

--------------------------------

### Python console session

Source: https://rst2pdf.org/manual.html

Example of Python console interaction.

```python
>>> my_string="python is great"
>>> my_string.find('great')
10
>>> my_string.startswith('py')
True
```

--------------------------------

### Pipe Usage Examples

Source: https://rst2pdf.org/_sources/manual.rst.txt

Examples of using rst2pdf within a Linux pipe to process text streams.

```bash
cat readme.txt | rst2pdf | gzip -c > readme.pdf.gz
```

--------------------------------

### Verify font installation

Source: https://rst2pdf.org/_sources/manual.rst.txt

Command to check if a font is correctly recognized by the system using fc-match.

```bash
$ fc-match fonty
fonty.ttf: "Fonty" "Normal"
```

--------------------------------

### Define Table Commands

Source: https://rst2pdf.org/_sources/manual.rst.txt

Examples of defining table commands, noting that commands are not cumulative and must be fully redefined.

```json
"commands": [ [ "VALIGN", [ 0, 0 ], [ -1, -1 ], "TOP" ] ]
```

```json
"commands": [ [ "LINEAFTER", [ 0, 0 ], [ 1, -1 ], .25, "black" ] ]
```

```json
"commands": [
    [ "VALIGN", [ 0, 0 ], [ -1, -1 ], "TOP" ],
    [ "LINEAFTER", [ 0, 0 ], [ 1, -1 ], .25, "black" ]
]
```

--------------------------------

### Configure embedded fonts

Source: https://rst2pdf.org/_sources/manual.rst.txt

Examples for embedding TrueType fonts, including single-variant fallbacks.

```yaml
embeddedFonts: []
```

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

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

--------------------------------

### Define Table Inner Grid Style

Source: https://rst2pdf.org/_sources/manual.rst.txt

Example of applying an INNERGRID command to a table style.

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

--------------------------------

### Sample ReStructured Text file

Source: https://rst2pdf.org/index.html

A basic example of a ReStructured Text file structure for PDF generation.

```rst
PDF Documents From Your Text Editor
###################################

This tool uses a plain text format for content, then applies styles to make the nice document you see here.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aliquam maximus tortor sem, vel pellentesque leo fringilla et. Aliquam imperdiet nisi eget dui finibus sagittis. Nunc malesuada libero vel dignissim pharetra. Cras egestas vehicula quam, et accumsan arcu lacinia auctor. Integer imperdiet sagittis justo, vel varius nulla dapibus finibus. Cras rhoncus mattis pellentesque. Quisque vel sapien sed tellus convallis accumsan. Praesent volutpat sapien at lacinia scelerisque. Phasellus neque libero, consectetur in neque id, egestas elementum nisl.

Mauris eu dolor non massa auctor suscipit. Donec sit amet aliquet eros, id sodales leo. Duis erat ipsum, laoreet eget nulla at, euismod ullamcorper mi. Curabitur vel orci a libero ullamcorper finibus. Sed vel lectus sapien. Praesent mollis et dui at laoreet. Donec eleifend, nunc nec bibendum luctus, massa lorem vestibulum justo, a convallis nunc turpis ut urna. Proin venenatis erat et ante convallis efficitur. Lorem ipsum dolor sit amet, consectetur adipiscing elit. In neque turpis, sollicitudin maximus egestas sed, finibus a odio. Nam eu eros id enim vehicula hendrerit at vel orci. Curabitur volutpat tempor purus ut auctor. Mauris vulputate sollicitudin porttitor. Nunc consectetur lectus nibh, et commodo purus porttitor ut. Nulla facilisi.

Further Sections, Headings, etc
===============================

Sed id interdum quam. Donec suscipit, justo ac blandit vestibulum, massa est semper dolor, vel sodales nulla metus eu purus. In risus tortor, interdum pellentesque dolor a, rhoncus volutpat orci. Ut commodo purus orci, non aliquet massa maximus in. Morbi semper dui ipsum, a dictum nisi pretium ut. Vestibulum bibendum lacinia viverra. In hac habitasse platea dictumst. Nunc vestibulum maximus mollis. Cras suscipit dictum condimentum. Nam vulputate, enim at gravida placerat, tellus nibh accumsan ligula, auctor ornare purus leo ac orci. Quisque ultricies dictum purus. In facilisis feugiat suscipit.
```

--------------------------------

### Display Package Version and Revision

Source: https://rst2pdf.org/_sources/manual.rst.txt

Use the version and revision roles to retrieve metadata from installed Python packages. The package must be present in the current environment.

```rst
Welcome to rst2pdf :version:`rst2pdf` (:revision:`rst2pdf`)!
```

--------------------------------

### Code block with line numbers

Source: https://rst2pdf.org/manual.html

Example of a code block displaying line numbers.

```text
1def myFun(x,y):
2    print x+y
```

--------------------------------

### Render Mathematical Formulae

Source: https://rst2pdf.org/_sources/manual.rst.txt

Use the math directive for block-level formulae and the math role for inline notation. Requires Matplotlib to be installed.

```rst
.. math::

   \frac{2 \pm \sqrt{7}}{3}
```

```rst
This is :math:`\pi`
```

--------------------------------

### Literal and Code Blocks

Source: https://rst2pdf.org/_sources/manual.rst.txt

Examples of literal and code block syntax in reStructuredText.

```rst
A literal block::

    This is a literal block.

A code block:

.. code-block:: python

    def x(y):
        print y**2
```

--------------------------------

### Configure Hyphenation Styles

Source: https://rst2pdf.org/_sources/manual.rst.txt

Enable hyphenation by installing pyphen and configuring the hyphenationLang and embeddedHyphenation options in your style definitions.

```yaml
base:
  hyphenationLang: en-US
  embeddedHyphenation: 1
```

```yaml
bodytext_es:
  parent: bodytext
  hyphenationLang: es-ES
  embeddedHyphenation: 1
```

--------------------------------

### Specify Image Dimensions

Source: https://rst2pdf.org/_sources/manual.rst.txt

Examples of defining image width using various units like inches, percentages, or centimeters.

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

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

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

--------------------------------

### Define custom font in stylesheet

Source: https://rst2pdf.org/_sources/manual.rst.txt

Example of declaring a custom font name within a style definition.

```yaml
normal:
  fontName: fonty
```

--------------------------------

### Set Page Counter

Source: https://rst2pdf.org/_sources/manual.rst.txt

Configures the page numbering style and starting value using the raw PDF directive.

```rst
.. raw:: pdf

    SetPageCounter 0 lowerroman
```

--------------------------------

### Print the default stylesheet

Source: https://rst2pdf.org/_sources/manual.rst.txt

Output the contents of the default stylesheet to stdout for use as a base template.

```bash
rst2pdf --print-stylesheet
```

--------------------------------

### Specify Template Usage

Source: https://rst2pdf.org/manual.html

Sets the initial template in the stylesheet and triggers a template change in the document.

```yaml
pageSetup:
  firstTemplate: oneColumn

```

```rst
.. raw:: pdf

   PageBreak twoColumn

```

--------------------------------

### List of TableStyle commands

Source: https://rst2pdf.org/manual.html

A reference list of available TableStyle commands for Reportlab-based table rendering.

```text
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
```

--------------------------------

### Apply multiple stylesheets to a document

Source: https://rst2pdf.org/_sources/manual.rst.txt

Use the -s flag to chain multiple stylesheet names, which are applied in the order provided.

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

--------------------------------

### Specify Stylesheets via CLI

Source: https://rst2pdf.org/_sources/manual.rst.txt

Use the -s flag to apply one or more stylesheets to the PDF generation process.

```bash
rst2pdf mydoc.rst -s mystyles
```

```bash
rst2pdf mydoc.rst -s a4,mystyles,murphy
```

--------------------------------

### Apply Custom Stylesheet

Source: https://rst2pdf.org/_sources/manual.rst.txt

Command line usage for applying a custom stylesheet alongside a built-in one.

```bash
rst2pdf mydoc.rst -o mydoc.pdf -s mystyle.json,murphy
```

--------------------------------

### Configure code-block options

Source: https://rst2pdf.org/_sources/manual.rst.txt

List of available configuration options for the code-block directive, mirroring Pygments settings.

```text
                                'stripnl' : string_bool,
                                'stripall': string_bool,
                                'ensurenl': string_bool,
                                'tabsize' : directives.positive_int,
                                'encoding': directives.encoding,
                                # Lua
                                'func_name_hightlighting':string_bool,
                                'disabled_modules': string_list,
                                # Python Console
                                'python3': string_bool,
                                # Delphi
                                'turbopascal':string_bool,
                                'delphi' :string_bool,
                                'freepascal': string_bool,
                                'units': string_list,
                                # Modula2
                                'pim'   : string_bool,
                                'iso'   : string_bool,
                                'objm2' : string_bool,
                                'gm2ext': string_bool,
                                # CSharp
                                'unicodelevel' : csharp_unicodelevel,
                                # Literate haskell
                                'litstyle' : lhs_litstyle,
                                # Raw
                                'compress': raw_compress,
                                # Rst
                                'handlecodeblocks': string_bool,
                                # Php
                                'startinline': string_bool,
                                'funcnamehighlighting': string_bool,
                                'disabledmodules': string_list,
```

--------------------------------

### Configure Headers and Footers

Source: https://rst2pdf.org/_sources/manual.rst.txt

Use the header or footer directive to define content that appears on every page.

```rst
.. header::

   This will be at the top of every page.
```

--------------------------------

### Configure Column Widths

Source: https://rst2pdf.org/_sources/manual.rst.txt

Set column widths for a table, where null indicates auto-calculation.

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

--------------------------------

### Migrate Stylesheet Formats

Source: https://rst2pdf.org/manual.html

Convert legacy RSON or JSON stylesheets to the recommended YAML format using the provided utility.

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

```bash
python3 -m rst2pdf.style2yaml example.style
```

--------------------------------

### Use historical default stylesheet

Source: https://rst2pdf.org/_sources/manual.rst.txt

Apply the rst2pdf-0-9 style to maintain compatibility with older stylesheet formats during migration.

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

--------------------------------

### Convert legacy stylesheet to YAML

Source: https://rst2pdf.org/_sources/manual.rst.txt

Use the style2yaml utility to migrate outdated JSON or RSON stylesheet formats.

```bash
python3 -m rst2pdf.style2yaml example.style
```

--------------------------------

### Update build scripts for PDF generation

Source: https://rst2pdf.org/_sources/manual.rst.txt

Integration steps for Makefile and make.bat to support the pdf build target.

```makefile
pdf:
    $(SPHINXBUILD) -b pdf $(ALLSPHINXOPTS) _build/pdf
    @echo
    @echo "Build finished. The PDF files are in _build/pdf."
```

```bat
if "%1" == "pdf" (
    %SPHINXBUILD% -b pdf %ALLSPHINXOPTS% %BUILDDIR%/pdf
    echo.
    echo.Build finished. The PDF files are in %BUILDDIR%/pdf
    goto end
)
```

--------------------------------

### Using the oddeven directive

Source: https://rst2pdf.org/manual.html

Defines content that alternates between odd and even pages. Requires wrapping complex content in containers.

```rst
.. oddeven::

    .. container::

        This will appear on odd pages.

        Both paragraphs in the container are for odd pages.

    This will appear on even pages. It's a single paragraph, so no need for
    containers.
```

--------------------------------

### Apply Stylesheets to PDF Generation

Source: https://rst2pdf.org/manual.html

Use the -s flag to specify one or more comma-separated stylesheets. Stylesheets are applied in order, with later entries taking precedence.

```bash
rst2pdf mydoc.rst -s mystyles
```

```bash
rst2pdf mydoc.rst -s a4,mystyles,murphy
```

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

--------------------------------

### Create PDF handouts with pdfjam

Source: https://rst2pdf.org/index.html

Generates a multi-slide handout layout from an existing PDF file, useful for printing multiple slides per page.

```bash
pdfjam --suffix handout --nup '4x3' --frame 'true' --noautoscale 'false' --delta '0.2cm 2cm' --scale '0.9' --landscape -- ${FILE}.pdf -
```

--------------------------------

### Enable hyphenation globally

Source: https://rst2pdf.org/manual.html

Configure the base style to apply hyphenation across the entire document.

```yaml
base:
  hyphenationLang: en-US
  embeddedHyphenation: 1

```

--------------------------------

### Configuring Global Font Aliases

Source: https://rst2pdf.org/manual.html

Map custom font names to standard aliases to use them as the document base font.

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

```

--------------------------------

### Configure Element Margins

Source: https://rst2pdf.org/_sources/manual.rst.txt

Sets margins and gutter space for page layout elements.

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

--------------------------------

### Configure Widows and Orphans

Source: https://rst2pdf.org/_sources/manual.rst.txt

Sets constraints for paragraph widows and orphans passed to ReportLab.

```yaml
allowWidows: 5
allowOrphans: 4
```

--------------------------------

### Project and dependency licenses

Source: https://rst2pdf.org/_sources/manual.rst.txt

License information for rst2pdf and included ReportLab fragments.

```text
Copyright (c) 2007-2020 Roberto Alsina and the contributors to the rst2pdf project

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.
```

```text
Copyright (c) 2000-2008, ReportLab Inc.
All rights reserved.

Redistribution and use in source and binary forms, with or without modification,
are permitted provided that the following conditions are met:

* Redistributions of source code must retain the above copyright notice,
  this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright notice,
  this list of conditions and the following disclaimer in the documentation
  and/or other materials provided with the distribution.
* Neither the name of the company nor the names of its contributors may be
  used to endorse or promote products derived from this software without
  specific prior written permission.
```

--------------------------------

### Define PDF output options in Sphinx

Source: https://rst2pdf.org/_sources/manual.rst.txt

Configure PDF document generation, stylesheets, and various formatting options within the Sphinx conf.py file.

```python
# -- Options for PDF output --------------------------------------------------

# Grouping the document tree into PDF files. List of tuples
# (source start file, target name, title, author, options).
#
# If there is more than one author, separate them with \\.
# For example: r'Guido van Rossum\\Fred L. Drake, Jr., editor'
#
# The options element is a dictionary that lets you override
# this config per-document. For example:
#
# ('index', 'MyProject', 'My Project', 'Author Name', {'pdf_compressed': True})
#
# would mean that specific document would be compressed
# regardless of the global 'pdf_compressed' setting.

pdf_documents = [
    ('index', 'MyProject', 'My Project', 'Author Name'),
]

# A comma-separated list of custom stylesheets. Example:
pdf_stylesheets = ['sphinx', 'a4']

# A list of folders to search for stylesheets. Example:
pdf_style_path = ['.', '_styles']

# Create a compressed PDF
# Use True/False or 1/0
# Example: compressed=True
# pdf_compressed = False

# A colon-separated list of folders to search for fonts. Example:
# pdf_font_path = ['/usr/share/fonts', '/usr/share/texmf-dist/fonts/']

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

# Mode for literal blocks wider than the frame. Can be
# overflow, shrink or truncate
# pdf_fit_mode = "shrink"

# Section level that forces a break page.
# For example: 1 means top-level sections start in a new page
# 0 means disabled
# pdf_break_level = 0

# When a section starts in a new page, force it to be 'even', 'odd',
# or just use 'any'
# pdf_breakside = 'any'

# Insert footnotes where they are defined instead of
# at the end.
# pdf_inline_footnotes = True

# verbosity level. 0 1 or 2
# pdf_verbosity = 0

# If false, no index is generated.
# pdf_use_index = True

# If false, no modindex is generated.
# pdf_use_modindex = True

# If false, no coverpage is generated.
# pdf_use_coverpage = True

# Name of the cover page template to use
# pdf_cover_template = 'sphinxcover.tmpl'

# Label to use as a prefix for the subtitle on the cover page
# subtitle_prefix = 'version'
```

--------------------------------

### Implement Frame Breaks

Source: https://rst2pdf.org/manual.html

Use FrameBreak to force a jump to the next frame if insufficient vertical space remains.

```rst
.. raw:: pdf

   FrameBreak 50

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

--------------------------------

### Configure Border Styles

Source: https://rst2pdf.org/_sources/manual.rst.txt

Defines border appearance including padding, width, and radius.

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

--------------------------------

### Configure PDF output options in conf.py

Source: https://rst2pdf.org/manual.html

Define PDF-specific settings such as document grouping, stylesheets, and formatting preferences at the end of your conf.py file.

```python
# -- Options for PDF output --------------------------------------------------

# Grouping the document tree into PDF files. List of tuples
# (source start file, target name, title, author, options).
#
# If there is more than one author, separate them with \\.
# For example: r'Guido van Rossum\\Fred L. Drake, Jr., editor'
#
# The options element is a dictionary that lets you override
# this config per-document. For example:
#
# ('index', 'MyProject', 'My Project', 'Author Name', {'pdf_compressed': True})
#
# would mean that specific document would be compressed
# regardless of the global 'pdf_compressed' setting.

pdf_documents = [
    ('index', 'MyProject', 'My Project', 'Author Name'),
]

# A comma-separated list of custom stylesheets. Example:
pdf_stylesheets = ['sphinx', 'a4']

# A list of folders to search for stylesheets. Example:
pdf_style_path = ['.', '_styles']

# Create a compressed PDF
# Use True/False or 1/0
# Example: compressed=True
# pdf_compressed = False

# A colon-separated list of folders to search for fonts. Example:
# pdf_font_path = ['/usr/share/fonts', '/usr/share/texmf-dist/fonts/']

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

# Mode for literal blocks wider than the frame. Can be
# overflow, shrink or truncate
# pdf_fit_mode = "shrink"

# Section level that forces a break page.
# For example: 1 means top-level sections start in a new page
# 0 means disabled
# pdf_break_level = 0

# When a section starts in a new page, force it to be 'even', 'odd',
# or just use 'any'
# pdf_breakside = 'any'

# Insert footnotes where they are defined instead of
# at the end.
# pdf_inline_footnotes = True

# verbosity level. 0 1 or 2
# pdf_verbosity = 0

# If false, no index is generated.
# pdf_use_index = True

# If false, no modindex is generated.
# pdf_use_modindex = True

# If false, no coverpage is generated.
# pdf_use_coverpage = True

# Name of the cover page template to use
# pdf_cover_template = 'sphinxcover.tmpl'

# Label to use as a prefix for the subtitle on the cover page
# subtitle_prefix = 'version'

# Documents to append as an appendix to all manuals.
# pdf_appendices = []

# Enable experimental feature to split table cells. Use it
# if you get "DelayedTable too big" errors
# pdf_splittables = False

# Set the default DPI for images
# pdf_default_dpi = 72

# Enable rst2pdf extension modules
# pdf_extensions = []

# Page template name for "regular" pages
# pdf_page_template = 'cutePage'

# Show Table Of Contents at the beginning?
# pdf_use_toc = True

# How many levels deep should the table of contents be?
pdf_toc_depth = 9999

# Add section number to section references
pdf_use_numbered_links = False

# Background images fitting mode
pdf_fit_background_mode = 'scale'

# Repeat table header on tables that cross a page boundary?
pdf_repeat_table_rows = True

# Enable smart quotes (1, 2 or 3) or disable by setting to 0
pdf_smartquotes = 0
```

--------------------------------

### Inserting mathematical formulae

Source: https://rst2pdf.org/manual.html

Uses the math directive to render LaTeX-style equations as text in the PDF.

```rst
.. math::

   \frac{2 \pm \sqrt{7}}{3}
```

--------------------------------

### Automate PDF recompilation with nodemon

Source: https://rst2pdf.org/index.html

Use this command to watch for changes in .rst or .style files and trigger an automatic rst2pdf build.

```bash
nodemon --ext rst,style --exec 'rst2pdf input.rst'
```

--------------------------------

### Define Page Templates

Source: https://rst2pdf.org/_sources/manual.rst.txt

Configuration structure for defining page templates with frames and visibility settings.

```yaml
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%]
```

--------------------------------

### Configure Bullet List Styles

Source: https://rst2pdf.org/_sources/manual.rst.txt

Defines font and indentation properties for bullet points in a list.

```yaml
bulletFontName: Helvetica
bulletFontSize: 10
bulletText: "•"
bulletIndent: 0
```

--------------------------------

### Set First Line Indent

Source: https://rst2pdf.org/_sources/manual.rst.txt

Configures the indentation for the first line of a paragraph.

```yaml
firstLineIndent: 0
```

--------------------------------

### Configure Page Transitions

Source: https://rst2pdf.org/_sources/manual.rst.txt

Sets visual effects for page changes in presentation mode, typically placed before a PageBreak.

```rst
.. raw:: pdf

   Transition effect duration [optional arguments]
```

```rst
.. raw:: pdf

   Transition Glitter 3 90
```

```rst
.. raw:: pdf

   Transition Dissolve 1
   PageBreak
```

--------------------------------

### Configure rst2pdf settings

Source: https://rst2pdf.org/_sources/manual.rst.txt

Configuration variables for customizing PDF output behavior in rst2pdf.

```python
pdf_toc_depth = 9999

# Add section number to section references
pdf_use_numbered_links = False

# Background images fitting mode
pdf_fit_background_mode = 'scale'

# Repeat table header on tables that cross a page boundary?
pdf_repeat_table_rows = True

# Enable smart quotes (1, 2 or 3) or disable by setting to 0
pdf_smartquotes = 0
```

--------------------------------

### Set Paragraph Alignment

Source: https://rst2pdf.org/_sources/manual.rst.txt

Defines the justification for paragraph text.

```yaml
alignment: TA_LEFT
```

--------------------------------

### Convert ReStructuredText to PDF via CLI

Source: https://rst2pdf.org/_sources/manual.rst.txt

Basic command-line usage for converting rst files to PDF using pipes or direct file input.

```bash
curl http://docutils.sourceforge.net/docs/user/rst/quickstart.txt | rst2pdf > quickstart.pdf
```

```bash
cat readme.txt | rst2pdf -o readme.pdf
```

```bash
rst2pdf -o - readme.txt > output.pdf
```

--------------------------------

### Configure Indentation

Source: https://rst2pdf.org/_sources/manual.rst.txt

Sets left and right indentation values.

```yaml
leftIndent: 0
rightIndent: 0
```

--------------------------------

### Use raw PDF directives

Source: https://rst2pdf.org/_sources/manual.rst.txt

Inserting page breaks and spacers using the raw directive.

```rst
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.
```

--------------------------------

### Switch Page Template

Source: https://rst2pdf.org/_sources/manual.rst.txt

Using a raw directive to trigger a page break and switch templates.

```rst
.. raw:: pdf

   PageBreak twoColumn
```

--------------------------------

### Generate PDF from ReStructured Text

Source: https://rst2pdf.org/index.html

Command to convert a .rst file into a .pdf document.

```bash
rst2pdf sample.rst
```

--------------------------------

### Global Font Size via Base Style

Source: https://rst2pdf.org/_sources/manual.rst.txt

Sets the base font size, which is inherited by all other styles.

```yaml
styles:
  base:
    fontSize: 12
```

--------------------------------

### Using the math role for inline notation

Source: https://rst2pdf.org/manual.html

Embeds mathematical symbols as images within a line of text.

```rst
This is :math:`\pi`
```

--------------------------------

### Configure language-specific styles

Source: https://rst2pdf.org/manual.html

Inherit from existing styles to apply specific hyphenation rules for different languages.

```yaml
bodytext_es:
  parent: bodytext
  hyphenationLang: es-ES
  embeddedHyphenation: 1

```

--------------------------------

### Include external files in code-block

Source: https://rst2pdf.org/_sources/manual.rst.txt

Use the :include: option to pull content from an external file into a code-block.

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

--------------------------------

### Set Font Size Percentage

Source: https://rst2pdf.org/_sources/manual.rst.txt

Defines font size as a percentage of the default.

```yaml
fontSize: 150%
```

--------------------------------

### Configure Sphinx extensions for rst2pdf

Source: https://rst2pdf.org/_sources/manual.rst.txt

Add the rst2pdf builder to the extensions list in your Sphinx conf.py file.

```python
extensions = ['sphinx.ext.autodoc','rst2pdf.pdfbuilder']
```

--------------------------------

### Apply Table Class

Source: https://rst2pdf.org/_sources/manual.rst.txt

Applying a custom class to a table for styling purposes.

```rst
.. class:: thick

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

--------------------------------

### Define Font Aliases

Source: https://rst2pdf.org/_sources/manual.rst.txt

Mapping logical font names to specific PDF fonts.

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

--------------------------------

### Custom Page Dimensions

Source: https://rst2pdf.org/_sources/manual.rst.txt

Configures non-standard page dimensions by setting size to null.

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

--------------------------------

### Configure Word Wrap

Source: https://rst2pdf.org/_sources/manual.rst.txt

Controls word wrapping behavior for text elements.

```yaml
wordWrap: None
```

--------------------------------

### Add Text Annotations

Source: https://rst2pdf.org/_sources/manual.rst.txt

Adds meta notes to a page using the raw PDF directive.

```rst
.. raw:: pdf

   TextAnnotation "text to add" [optional position]
```

--------------------------------

### Insert Page Breaks

Source: https://rst2pdf.org/_sources/manual.rst.txt

Commands to force page breaks, optionally specifying a template or background image.

```rst
PageBreak twoColumn
```

```rst
PageBreak mainPage background="images/background.jpg"
```

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

--------------------------------

### Highlight Specific Lines

Source: https://rst2pdf.org/_sources/manual.rst.txt

Emphasize specific lines using the hl_lines option.

```rst
.. code-block:: python
   :hl_lines: 2 3

   def myFun(x,y):
       print "line a"
       print "line b"
       print "line c"
```

--------------------------------

### Configure Vertical Spacing

Source: https://rst2pdf.org/_sources/manual.rst.txt

Sets the vertical space before and after an element.

```yaml
spaceBefore: 4
spaceAfter: 8
```

--------------------------------

### Configure font path via CLI

Source: https://rst2pdf.org/_sources/manual.rst.txt

Command to specify the font path when generating a PDF.

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

--------------------------------

### Apply multiple styles to a paragraph

Source: https://rst2pdf.org/manual.html

List multiple styles in the class directive; properties in right-hand styles override those to the left.

```rst
.. class:: special bluetext redtext

    This paragraph is special and is red.

This one is not.
```

--------------------------------

### Configure font aliases

Source: https://rst2pdf.org/_sources/manual.rst.txt

Mapping document font roles to specific embedded font files.

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

--------------------------------

### Use Counter Role

Source: https://rst2pdf.org/_sources/manual.rst.txt

Implements custom counters within text using the :counter: role.

```rst
Start a counter called seq1 that starts from 1: :counter:`seq1`
Now this should print 2: :counter:`seq1`

You can start counters from any number (this prints 12): :counter:`seq2:12`

And have any number of counters with any name: :counter:`figures`

So ``#seq1-2`` should link to `the number 2 above <#seq1-2>`_
```

--------------------------------

### Fallback for Missing Font Variants

Source: https://rst2pdf.org/manual.html

Use the normal variant for all slots if specific bold or italic files are unavailable.

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

```

--------------------------------

### Set font for specific style

Source: https://rst2pdf.org/_sources/manual.rst.txt

Applying a specific font to a heading style.

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

--------------------------------

### Syntax Highlighted Python Code

Source: https://rst2pdf.org/_sources/manual.rst.txt

Basic usage of the code-block directive for Python.

```rst
.. code-block:: python

    def myFun(x,y):
        print x+y
```

```python
def myFun(x,y):
    print x+y
```

--------------------------------

### Set Background Color

Source: https://rst2pdf.org/_sources/manual.rst.txt

Sets the background color of an element.

```yaml
backColor: beige
```

--------------------------------

### Frame Definition Syntax

Source: https://rst2pdf.org/_sources/manual.rst.txt

The list structure defining frame geometry and padding.

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

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

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

--------------------------------

### Embedding Font Variants

Source: https://rst2pdf.org/manual.html

Define a list of font files for normal, bold, italic, and bold-italic variants.

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

```

--------------------------------

### Include Python code with code-block

Source: https://rst2pdf.org/manual.html

Use the code-block directive to include syntax-highlighted Python code in your document.

```rst
.. code-block:: python

    def myFun(x,y):
        print x+y
```

--------------------------------

### Apply Custom Styles to Content

Source: https://rst2pdf.org/_sources/manual.rst.txt

Use the class directive to apply a specific style, such as a language-specific hyphenation style, to a block of text.

```rst
.. class:: bodytext_es

Debo a la conjunción de un espejo y de una enciclopedia el descubrimiento de Uqbar.
El espejo inquietaba el fondo de un corredor en una quinta de la calle Gaona,
en Ramos Mejía; la enciclopedia falazmente se llama *The Anglo-American Cyclopaedía*
(New York, 1917) y es una reimpresión literal, pero también morosa, de la
*Encyclopaedia Britannica* de 1902.
```

--------------------------------

### Set Text Color

Source: https://rst2pdf.org/_sources/manual.rst.txt

Specifies the text color using a name or hex code.

```yaml
textColor: black
```

--------------------------------

### Set Body Text Alignment

Source: https://rst2pdf.org/_sources/manual.rst.txt

Configures paragraph alignment for body text elements.

```yaml
styles:
 - bodytext:
      alignment: TA_LEFT
```
Tokens:
Raw