rst2pdf

0.105 · active · verified Thu Apr 16

rst2pdf is a Python library and command-line tool for converting reStructuredText documents to PDF format, leveraging the ReportLab library for PDF generation. It supports various reStructuredText features, including styles, images, and syntax highlighting. The current version is 0.105, and it maintains an active release cadence with frequent minor updates.

Common errors

```
ModuleNotFoundError: No module named 'reportlab'
```
cause The core dependency `reportlab` is not installed or not accessible in the current Python environment.

fix Ensure `reportlab` is installed: `pip install reportlab`. If installed, check your Python environment's path.
```
ModuleNotFoundError: No module named 'docutils'
```
cause The core dependency `docutils` is not installed or not accessible in the current Python environment.

fix Ensure `docutils` is installed: `pip install docutils`. This library is essential for parsing reStructuredText.
```
rst2pdf.createpdf.Rst2PdfError: Unsupported image type: .webp
```
cause rst2pdf (via Pillow and ReportLab) may not support certain image formats directly, or the necessary underlying image processing libraries (e.g., for WebP) are missing from your system.

fix Convert images to widely supported formats like PNG or JPEG. Ensure Pillow is fully installed with relevant optional backend libraries if attempting less common types. For example, on Linux, `sudo apt-get install libwebp-dev` might be needed for WebP support with Pillow.
```
ERROR: Could not find a suitable font. Make sure some fonts are installed.
```
cause ReportLab (used by rst2pdf) cannot locate system fonts, especially if you're using a minimal environment or custom styles that specify non-existent fonts.

fix Ensure basic system fonts are installed (e.g., `fonts-freefont-ttf` on Debian/Ubuntu). For custom fonts, provide their paths in your stylesheet or ensure they are accessible in a standard font directory that ReportLab can scan.

Warnings

breaking rst2pdf version 0.100 dropped support for Python versions below 3.6, and current versions (0.105) require Python >=3.10. Older Python versions will result in installation failures or runtime errors.
Fix: Upgrade your Python environment to 3.10 or newer. Check `requires_python` on PyPI for the exact version range if using an older rst2pdf version.
gotcha rst2pdf heavily relies on `ReportLab` and `Docutils` as its core rendering engines. Issues with PDF output (e.g., font rendering, complex layouts, specific styling) or reStructuredText parsing often stem from limitations or quirks within these underlying libraries, not always directly from rst2pdf itself.
Fix: Consult `ReportLab` and `Docutils` documentation for advanced styling, font embedding, or troubleshooting parsing issues. Ensure system-level dependencies for image processing (e.g., `libjpeg` for Pillow) are met for full functionality.
deprecated As of version 0.104, rst2pdf removed its direct dependency on the `smartypants` library and now uses `docutils`'s built-in typography features for converting ASCII quotes to curly quotes and similar transformations. This might result in subtle rendering differences for documents that relied on specific `smartypants` behavior.
Fix: Review PDF output after upgrading to ensure typographical changes are as expected. If specific `smartypants` behavior is critical, consider pinning to an older rst2pdf version or pre-processing your reStructuredText.

Install

pip install rst2pdf Install stable version

Imports

rst2pdf
```
from rst2pdf.createpdf import rst2pdf
```

Quickstart

This quickstart demonstrates how to use the rst2pdf Python API to convert a reStructuredText string into a PDF file. The `rst2pdf` function from `rst2pdf.createpdf` is the primary programmatic interface.

import os
from rst2pdf.createpdf import rst2pdf

rst_content = '''
My PDF Document
===============

This is a sample reStructuredText document converted to PDF.

* Item A
* Item B

.. code-block:: python

   print("Hello, rst2pdf!")

.. note::
   This is a generated PDF using rst2pdf.
'''

output_filename = "sample_document.pdf"

try:
    # The rst2pdf function can take a string for 'text' and a filename for 'output'
    rst2pdf(text=rst_content, output=output_filename)
    print(f"PDF successfully created: {output_filename}")
except Exception as e:
    print(f"Error creating PDF: {e}")
    print("Please ensure all core dependencies like docutils and reportlab are correctly installed.")

view raw JSON →