Options¶

The plugin allows users to pass in both global and local options. Some of these global options are used as default options when local options are not set or the plugin’s default values are used by the PDF plugin.

Global Options¶

The global options are passed to the plugin through the conf.py file and they are:

# Sphinx-PDF-Generate configurations
pdfgen_verbose = False
pdfgen_site_url = "https://isolveit.github.io/sphinx-pdf-generate/"
pdfgen_debug = True
pdfgen_debug_target = "index.rst"
pdfgen_author = "Sphinx-PDF"
pdfgen_author_logo = "_static/img/author-logo.png"
pdfgen_copyright = "2023, Sphinx-PDF"
pdfgen_disclaimer = "Disclaimer: Content can change at anytime and best to refer to website for latest information."
pdfgen_cover = True
pdfgen_cover_title = ""
pdfgen_cover_subtitle = ""
pdfgen_custom_template_path = ""
pdfgen_custom_css_path = ""
pdfgen_plugin_handler_path = "custom_code.py"
pdfgen_toc = True
pdfgen_toc_numbering = True
pdfgen_toc_title = "Contents"
pdfgen_toc_level = 6
pdfgen_cover_images = {
    "default": "https://example.com/cover.svg",
    "type1": "_static/img/type1.png",
}

for Cover¶

pdfgen_cover¶

Set the value to False if you don’t need a cover page.
default: True

pdfgen_cover_title¶

Set the title text on the cover page.
default: use project variable in your project’s conf.py

pdfgen_cover_subtitle¶

Set the subtitle text in cover page.
default: None

pdfgen_author¶

Set the author text.
default: use author variable in your project’s conf.py

pdfgen_author_logo¶

Provide a logo image which you can use in the cover page.
default: use html_logo variable in your project’s conf.py

pdfgen_copyright¶

Set the copyright text.
default: use copyright variable in your project’s conf.py

pdfgen_disclaimer¶

Set the disclaimer text.
default: None

pdfgen_cover_images¶

Set the cover image for specific document types.

The option takes a Python dictionary where the key must be the one of the values you specified for the pdf-type local pdf metadata option.

The value for a key must be the path to the image.
default: None

Example:

pdfgen_cover_images = {
    "default": "https://example.com/cover.svg",
    "home": "_static/img/home-cv-img.png",
    "options": "_static/img/options-cv-img.png",
    "customise": "_static/img/custom-cv-img.png",
}

for Heading and TOC¶

pdfgen_toc¶

Set the value to False if you don’t need a table of content section in the PDF document.
default: True

pdfgen_toc_title¶

Set the title text for the Table of Contents page.
default: Table of Contents

pdfgen_toc_level¶

Set the maximum heading level to show on the Table of Contents page. The option’s value is between 1 to 6.
default: 4

pdfgen_toc_numbering¶

Set the value to False if you don’t want your table of contents to be numbered in the PDF document.
default: True

… and more¶

pdfgen_custom_template_path¶

A relative path inside your documentation’s directory (i.e. relative to your project’s conf.py file). This folder is where you save the custom cover template files (e.g. cover.html).
default: None

pdfgen_custom_css_path¶

A relative path inside your documentation’s directory (i.e. relative to your project’s conf.py file). This folder is where you save the custom CSS file (i.e. pdf_custom.css).
default: None

pdfgen_theme_handler_path¶

This option allows you to specify a custom theme handler module for unsupported themes. The path must be relative to your project’s root (See example below).
default: None

conf.py:

pdfgen_theme_handler_path = "theme_handler.py"

project_root folder structure:

project_root
├── theme_handler.py
├── docs
    ├── conf.py
    ├── index.rst
    ├── _build
.
.

The theme_handler.py file should should contain these two functions below:

def get_stylesheet() -> str:
    """Function which returns the custom stylesheets for the theme you want to support"""


def modify_html(html: str, href: str) -> str:
    """Function which modifies the HTML to include where you want to place the PDF download button at

    :param html: HTML content you can modify
    :param href: URL path to the PDF document generated
    """

Example of the above functions being used:

# theme_handler.py

def get_stylesheet():
css_style = """.md-container {{
display: block;
padding-top: 0;
}}
.md-main {{
    display: block;
    height: inherit;
}}"""
return css_style


def modify_html(html: str, href: str):
    a_tag = f'<a class="pdf-icon" href="{href}" download title="Download PDF"></a>'

    # insert into HTML
    insert_point = '<div class="document">'
    html = html.replace(insert_point, insert_point + a_tag)
    return html

pdfgen_plugin_handler_path¶

This option allows you to add custom features to the PDF generator plugin. The path must be relative to your project’s root (See example below).
default: None

conf.py:

pdfgen_plugin_handler_path = "custom_code.py"

project_root folder structure:

project_root
├── custom_code.py
├── docs
    ├── conf.py
    ├── index.rst
    ├── _build

The custom_code.py file should should contain the main() function like below:

def some_function():
    """Just a function doing something"""
    return ""


def main(**kwargs) -> None:
    """Function called when the custom module is loaded and executed.

    :param **kwargs: Keyword arguments you can use in the function
    """

    variable = some_function()
    return variable

if __name__ == "__main__":
    main()

Example of the above function being used in a custom user plugin file called feature_addon.py:

# feature_addon.py

import re
from typing import List
from bs4 import BeautifulSoup, Tag


def main(**kwargs: BeautifulSoup) -> None:
    """Finds matching thumbnails and create their PDF versions"""
    soup = kwargs['soup']
    thumbnail_images = soup.find_all("img", attrs={"class": re.compile(r"product-img|img-thumbnail")})
    pdf_thumbnails: List[Tag] = []
    for img in thumbnail_images:
        pdf_figure = soup.new_tag("figure", attrs={"class": "align-center"})
        pdf_img: Tag = soup.new_tag("img", attrs={"src": img["src"], "alt": img["alt"]})
        pdf_figcaption = soup.new_tag("figcaption")
        figcaption_text = soup.new_tag("p", attrs={"class": "caption-text"})
        figcaption_text.append(img["alt"])
        pdf_figcaption.append(figcaption_text)

        pdf_figure.append(pdf_img)
        pdf_figure.append(pdf_figcaption)
        pdf_thumbnails.append(pdf_figure)

    # Create a div containing new PDF thumbnails.
    pdf_div: Tag = soup.new_tag("div", attrs={"class": "product-images pdf-only"})
    for thumbnail in pdf_thumbnails:
        pdf_div.append(thumbnail)

    # Insert PDF Thumbnails after div#gallery
    html_thumbnails_node = soup.find("div", attrs={"id": "gallery"})
    html_thumbnails_node.insert_after(pdf_div)


if __name__ == "__main__":
    main()

pdfgen_verbose¶

Setting this to True will show all WeasyPrint debug messages during the build.
default: False

pdfgen_debug (for development purposes only)¶

Setting this to True enables the debug mode which saves the HTML content used in generating the PDF files into a folder called pdf_html_debug. The pdf_html_debug folder is relative to the documentation output (build) directory.

This option is intended to help users in debugging and writing appropriate CSS styles for the HTML content used to generate the PDF documents.

default: False

pdfgen_debug_target (for development purposes only)¶

This option helps you to generate a PDF file for a single target document so you can fine-tune the PDF output. The value for debug_target should be the path to the target document in your project’s source directory or relative to your project’s conf.py file. Example: pdfgen_debug_target = "PCs/ARM/CS10600T070.rst.

This option is intended to help reduce the time spent by users in debugging a single document used to generate a PDF file.

default: None

pdfgen_site_url¶

This option allows you to set the site url for your documentation project. Example: pdfgen_site_url = "https://isolveit.github.io/sphinx-pdf-generate/"
default: http://127.0.0.1:8000

Local Options¶

The plugin allows you to set document specific options using the Sphinx File-wide metadata feature. If a local option is specified, it has higher precedence than the Global Options.

The local options are specified at the top of the RST file preceding any other markup like below:

:pdf-build: True
:pdf-filename: Plugin Options
:pdf-title: Options for Sphinx PDF Generate Plugin
:pdf-type: options
:pdf-revision: 0.1

The following options are available:

• pdf-build

• pdf-title

• pdf-subtitle

• pdf-type

• pdf-filename

• pdf-revision

pdf-build¶

Allows you to specify whether to generate a PDF file for the RST file or not. Value is True or False.
default: True

pdf-title¶

Set the title text on the cover page.
default: None

pdf-subtitle¶

Set the subtitle text on the cover page. The value of this option can be one or more text separated by pipe (|) symbol.

Example: :pdf-subtitle: text1 | text2
default: None

pdf-type¶

Set the document type.
default: document

pdf-filename¶

Set the filename to use in saving the generated PDF document.
default: None

pdf-revision¶

Set the document revision text on the cover page.
default: None