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/