Sphinx-SimplePDF

This Sphinx extension provides an easy way to build beautiful PDFs based on CSS rules.

It contains:

  • A PDF specific, CSS based Sphinx theme: sphinx_simplepdf.

  • A Sphinx builder, called simplepdf

  • Directives to

    • control different structures and content for HTML and PDF builds.

    • embed PDF inside HTML views.

It is using weasyprint as PDF generator.

Note

This extension is in a beta phase.

It is not bug free and documentation is also missing some minor stuff. You can help us to make it better by reporting bugs or by providing code/docs changes via a PR. The code is available on github: useblocks/sphinx-simplepdf

Showcase

Sphinx-SimplePDF Documentation
The PDF is based on the current HTML documentation.
Sphinx-SimplePDF Demo
A PDF containing different content types to check the handling of them by Sphinx-SimplePDF.

Quickstart

Install via pip install sphinx-simplepdf.

Then inside your Sphinx documentation folder run make simplepdf. Your PDF is available under _build/simplepdf.

Color and images can be changed by setting simplepdf_vars inside your conf.py file:

simplepdf_vars = {
    'primary': '#333333',
    'links': '#FF3333',
}

For more configuration options take a look into Configuration.

For PDF/HTML specific content, use the if-builder directive.

# conf.py
extensions = ['sphinx_simplepdf']
# rst file
.. if-builder:: simplepdf

   .. toctree::

      my_files
      specific_pdf_file

.. if-builder:: html

   .. toctree::

      my_files

   Other HTML specific content, which will not be part of the PDF.

Why another PDF builder?

You can use the Sphinx Latex builder to generate PDFs. And there is also the great rinohtype library.

But both have some drawbacks, which we try to avoid with this solution.

Latex distributions are quite big and Latex as language may not be the language of choice for everybody.

rinohtype makes a lot of things easier, but it does not support additional Sphinx extensions very well (if they are using visitor-functions). For instance is it hard to get PlantUML running with rinohtype.

But for sure, there are also scenarios where Sphinx-SimplePDF may not be the best solution. So if you are unhappy with Sphinx-SimplePDF please try the others as well :)

One last thing …

This theme is heavily based on the excellent work of Nekmo for the Sphinx Business Theme.

Without this work, this theme would never exist. Thanks for it ♥