Installation

From PyPi

pip install sphinx-simplepdf

From source

git clone git@github.com:useblocks/sphinx-simplepdf.git
cd sphinx-simplepdf
pip install .

Requirements

Sphinx-SimplePDF requires Sphinx version >= 4.4.4 to properly render the Table of Content with page counts.

macOS installation

If you are using macOS as operating system, the chance is high that the package pango gets not automatically installed when installing Sphinx-SimplePDF.

In this case please run also brew install pango.

Windows installation

Sphinx-SimplePDF is based on WeasypPrint, which is not so easy to get installed on Windows.

Please follow their instructions about how to install WeasyPrint on Windows.

Using Sphinx-SimplePDF directives

Sphinx-SimplePDF can be called directly after the installation.

However, if you want to use the included directives, like if-builder, you need to add Sphinx-SimplePDF to the list of extensions in your conf.py file:

extensions = [
    'sphinx_simplepdf',
    # additional extensions
]

ReadTheDocs configuration

Sphinx-SimplePDF can be also used on Read The Docs (RTD) to generate your PDF. As it is not supported by RTD by default, you need to create a .readthedocs.yaml configuration file on the root level of our project.

You can take the one from Sphinx-SimplePDF as a good example:

# .readthedocs.yaml
# Read the Docs configuration file
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details

# Required
version: 2

# Set the version of Python and other tools you might need
build:
  os: ubuntu-22.04
  apt_packages:
    - default-jre  # This seems to be ignored
  tools:
    python: "3.9"
  # We can only define the content of the final deployment, if we do the complete build on our own.apt_packages:
  # So we need to handle package installation, build start and copying the right files for deployment.
  commands:
    - pip install .
    - pip install -r demo/doc-requirements.txt
    - sphinx-build -M simplepdf demo demo/_build  # Use a different build-folder for a really clean build
    - pip install -r docs/doc-requirements.txt
    - sphinx-build -M simplepdf docs docs/_build2  # Use a different build-folder for a really clean build
    - cp demo/_build/simplepdf/Sphinx-SimplePDF-DEMO.pdf docs/_static/Sphinx-SimplePDF-DEMO.pdf
    - cp docs/_build2/simplepdf/Sphinx-SimplePDF.pdf docs/_static/Sphinx-SimplePDF.pdf
    - sphinx-build -M html docs docs/_build  # HTML latest, because it needs the built PDF files
    - mkdir -p _readthedocs/html/
    - cp -r docs/_build/html/* _readthedocs/html/