Configuration¶

simplepdf_vars¶

Sphinx-SimplePDF provides the config variable simplepdf_vars, which must be a dictionary. The key is used as identifier inside scss-files and the value must be a css/scss compatible string.

Example conf.py

simplepdf_vars = {
    'primary': '#FA2323',
    'secondary': '#379683',
    'cover': '#ffffff',
    'white': '#ffffff',
    'links': 'FA2323',
    'cover-bg': 'url(cover-bg.jpg) no-repeat center',
    'cover-overlay': 'rgba(250, 35, 35, 0.5)',
    'top-left-content': 'counter(page)',
    'bottom-center-content': '"Custom footer content"',
}

These values are used then inside the scss files, which define the PDF layout.

Config vars¶

primary:: Primary color
primary_opaque:: Primary color with opaqueness. Example rgba(150, 26, 26, .5)
secondary:: Secondary color
cover:: Text color on the cover
white:: A color representing white
links:: Color for links
cover-bg:: Cover background image. Can be a single color or even an image path.
cover-overlay:: RGB based color overlay for the cover-image. Example: rgba(250, 35, 35, 0.5)
top-left-content:: Text or css function to display on pdf output. Example: counter(page)
top-center-content:: Text or css function to display on pdf output.
top-right-content:: Text or css function to display on pdf output.
bottom-left-content:: Text or css function to display on pdf output.
bottom-center-content:: Text or css function to display on pdf output.
bottom-right-content:: Text or css function to display on pdf output.

All variables are defined inside sphinx_simplepdf/themes/simplepdf_theme/static/styles/sources/_variables.scss.

Hint

If a content-string shall be set, please make sure to use extra “ around the string. Example: ‘bottom-center-content’: ‘“Custom footer content”’.

Examples¶

The values from the configuration are taken as they are and injected into scss files, which are used to generate the css files. So each value or command, which is supported by scss, can be set.

Color selection¶

simplepdf_vars = {
    'primary': '#FA2323',
    'cover-overlay': 'rgba(250, 35, 35, 0.5)',
}

File references¶

simplepdf_vars = {
    'cover-bg': 'url(cover-bg.jpg) no-repeat center'
}

The file path must be relative to the Sphinx _static folder. So in the above example the image is stored under /_static/cover-bg.jpg.

SimplePDF docs¶

This is simplepdf_vars as it is used inside the Sphinx-SimplePDF conf.py file:

simplepdf_vars = {"cover-overlay": "rgba(150, 26, 26, 0.7)", "cover-bg": "url(cover-bg.jpg) no-repeat center"}

# use this to force using the weasyprint python API instead of building via the binary

simplepdf_file_name¶

Added in version 1.5.

File name of the resulting PDF file in the simplepdf build folder. If not set, the project name is used.

File name and extension can be set. But it should not be used to manipulate the output path.

Example:

simplepdf_file_name = "my_cool.pdf"

Default: project name

simplepdf_debug¶

A boolean value. If set to True, Sphinx-SimplePDF will add some debug information at the end of the PDF.

This contains data about the used Python Environment and the Sphinx project. It is mainly used if any problems occur and extra information is needed.

simplepdf_debug = True

You can see an example in our PDF Demo at the end of the file.

Warning

The debug output contains absolute file paths and maybe other critical information. Do not use for official PDF releases.

simplepdf_use_weasyprint_api¶

Added in version 1.6.

This forces simplepdf to use the weasyprint python API instead of calling the binary via subprocess.

simplepdf_use_weasyprint_api = True

Warning

Other variables like simplepdf_weasyprint_flags will not work when using the API.

simplepdf_weasyprint_flags¶

Added in version 1.5.

List of flags to pass to weasyprint subprocess. This may be helpful in debugging the pdf creation

simplepdf_weasyprint_flags = ['-v']

Warning

The flags should only pass switches to weasyprint, input and output file names are appended by Sphinx-SimplePDF

simplepdf_weasyprint_timeout¶

Added in version 1.5.

In rare cases weasyprint seems to run into infinite loops during processing of the input file. To avoid blocking CI jobs a timeout can be configured. The build is aborted with a subprocess.TimeoutExpired exception.

simplepdf_weasyprint_timeout = 300

simplepdf_weasyprint_retries¶

Added in version 1.6.

In rare cases weasyprint seems to run into infinite loops during processing of the input file. In case a subprocess.TimeoutExpired exception occurred and retries are configured weasyprint is started again.

simplepdf_weasyprint_retries = 1

simplepdf_theme¶

Added in version 1.5.

Name of the theme to use for PDF output. This overrides the default theme simplepdf_theme. The value must match both the Sphinx theme name and the importable Python module name.

simplepdf_theme = "my_custom_pdf_theme"

The theme module must define a get_scss_sources_path() function that returns the path to its SCSS sources directory. This is how the builder locates the SCSS files to compile into CSS for the PDF. Prefer returning an absolute path based on __file__ so behavior does not depend on Sphinx’s working directory.

Minimal example:

from os import path

def get_scss_sources_path():
    """Return the absolute path to the SCSS sources directory."""
    return path.join(path.abspath(path.dirname(__file__)), "static", "styles", "sources")

The SCSS sources directory should contain a main.scss file as the entry point. You can use the bundled simplepdf_theme as a reference for the expected directory structure and SCSS files.

Note

If the theme module cannot be imported or does not define get_scss_sources_path(), the builder falls back to the bundled simplepdf_theme SCSS sources and emits a warning.

simplepdf_theme_options¶

Added in version 1.5.

Additional options for the theme. The default theme simplepdf_theme inherits all options from the Sphinx Basic Theme.

simplepdf_theme options:

nocover:: Do not display cover pages (front and back cover)

simplepdf_weasyprint_filter¶

Added in version 1.6.

If weasyprint is used as executable the output contains warnings and errors from weasyprint. To reduce output noise the output can be filtered by a list of regular expressions given in this configuration option.

simplepdf_weasyprint_filter = ["WARNING: Ignored"]

To suppress all output, the quiet flag -q should be used.

simplepdf_html_hook¶

Added in version 1.7.

Path to a Python script that will be called to manipulate the HTML before PDF generation. The script must define a function named html_hook. This allows custom transformations using BeautifulSoup.

Note

Only one hook script is supported per build: simplepdf_html_hook must be a single path. Combine logic inside one script if you need multiple steps.

Format: "path/to/script.py"

The path can be absolute or relative to the conf.py directory.

Example conf.py:

simplepdf_html_hook = "./hooks/pdf_hook.py"

Example hook script (hooks/pdf_hook.py):

from bs4 import BeautifulSoup

def html_hook(soup, app):
    """
    Customize HTML before PDF generation.

    Args:
        soup: BeautifulSoup object with parsed HTML
        app: Sphinx application instance
    Returns:
        Modified BeautifulSoup object
    """
    # Example: Remove navigation elements
    for nav in soup.find_all("nav"):
        nav.decompose()

    # Example: Add watermark
    watermark = soup.new_tag("div", attrs={"class": "watermark"})
    watermark.string = "DRAFT"
    body = soup.find("body")
    if body:
        body.insert(0, watermark)

    return soup

Function signature:

The html_hook function must accept two arguments:

soup:: A BeautifulSoup object containing the parsed HTML
app:: The Sphinx application instance (provides access to config, srcdir, outdir, etc.)

The function must return a BeautifulSoup object.

Sphinx-SimplePDF

Navigation

Related Topics

Configuration¶

simplepdf_vars¶

Config vars¶

Examples¶

Color selection¶

File references¶

SimplePDF docs¶

simplepdf_file_name¶

simplepdf_debug¶

simplepdf_use_weasyprint_api¶

simplepdf_weasyprint_flags¶

simplepdf_weasyprint_timeout¶

simplepdf_weasyprint_retries¶

simplepdf_theme¶

simplepdf_theme_options¶

simplepdf_weasyprint_filter¶

simplepdf_html_hook¶