Sphinx PDF Generate

A Sphinx extension to generate individual PDF files for each documentation page.

Sphinx-PDF-Generate extension generates separate PDF files from each HTML page derived from your Sphinx RST files page in your Sphinx documentation using WeasyPrint.

The extension supports many advanced features such as table of contents, customisable cover page , support for CSS paged media module CSS paged media module , and using Sphinx page metadata to generate cover page.

If you find Sphinx-PDF Generate useful, please consider starring the project. Thank you!

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

Note

We recommend you install the extension in a Python virtualenv.

Install the package with pip

pip install sphinx-pdf-generate

Install from source repository

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

You can refer to the installation page for information.

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.