Requirements

1. This package requires Sphinx version 5.0 or higher.

2. Python 3.8 or higher

3. WeasyPrint depends on cairo, Pango and GDK-PixBuf which need to be installed separately. Please follow the installation instructions for your platform carefully:

   • Linux

   • MacOS

   • Windows

4. Explicit support for your Sphinx theme is probably required using custom CSS. As of now, the supported themes are Sphinx-Material and Sphinx-Immaterial. A generic version will just generate the PDF files and put the download link into a <link> tag.

Installation

pip install sphinx-pdf-generate

cd [YOUR_PROJECT_DIRECTORY]
git clone https://github.com/iSOLveIT/sphinx-pdf-generate
cd sphinx-pdf-generate
pip install -e .

Activate Extension

You can activate the extension in your conf.py file by adding the following:

extensions = ["sphinx_pdf_generate"]

You can then set the appropriate extension configuration. Visit the options page on our documentation website to read more.

Usage

You can generate PDF documents for your documentation project by using the command sphinx-pdf-generate sourcedir outdir as below:

$ sphinx-pdf-generate docs/source docs/_build/html

After the documentation build is complete, you should now see the following message at the end of your build output:

[sphinx-pdf-generate] Converting 7 file(s) to PDF took 12.1s

In your OUTPUTDIR e.g.(docs/_build/html) you should now have a PDF file for every RST document you decided to build.

You can refer to the quickstart page for a good introduction to Sphinx-PDF Generate.

Contributing

From reporting a bug to submitting a pull request: every contribution is appreciated and welcome. Report bugs, ask questions and request features using GitHub issues.

If you want to contribute to the code of this project, please read the Contribution Guidelines.

Special thanks

Many thanks to Terry Zhao the author of the MkDocs PDF Export Plugin and Jonathan Stoppani the author of the Sphinx-Autobuild Plugin.

Their projects inspired the creation of this plugin. We’ve used some of their code in this project.