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
andembed 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¶
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 ♥