Metadata-Version: 2.1
Name: sphinx-pdf-generate
Version: 0.0.3
Summary: A Sphinx extension to generate individual PDF files for each documentation page.
Home-page: https://github.com/iSOLveIT/sphinx-pdf-generate
License: MIT
Author: Duodu Randy
Author-email: duodurandy19@gmail.com
Maintainer: Duodu Randy
Maintainer-email: duodurandy19@gmail.com
Requires-Python: >=3.8.0,<4.0
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Framework :: Sphinx :: Extension
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Topic :: Documentation :: Sphinx
Classifier: Topic :: Software Development :: Build Tools
Provides-Extra: docs
Provides-Extra: immaterial
Requires-Dist: beautifulsoup4 (>=4.6.3)
Requires-Dist: colorama (>=0.4.6)
Requires-Dist: docutils (>=0.15)
Requires-Dist: jinja2 (>=3.0.0)
Requires-Dist: pathlib (>=1.0)
Requires-Dist: pypdf (>=3.6.0)
Requires-Dist: simple-file-checksum (>=1.2.2)
Requires-Dist: sphinx (>=5.0) ; extra == "docs"
Requires-Dist: weasyprint (>=54.0)
Project-URL: Documentation, https://isolveit.github.io/sphinx-pdf-generate/
Project-URL: Repository, https://github.com/iSOLveIT/sphinx-pdf-generate
Description-Content-Type: text/x-rst

.. _github-issues: https://github.com/iSOLveIT/sphinx-pdf-generate/issues

.. |github-issues| replace:: GitHub issues

.. _weasyprint-linux: https://weasyprint.readthedocs.io/en/latest/install.html#linux

.. |weasyprint-linux| replace:: Linux

.. _weasyprint-macos: https://weasyprint.readthedocs.io/en/latest/install.html#macos

.. |weasyprint-macos| replace:: MacOS

.. _weasyprint-windows: https://weasyprint.readthedocs.io/en/latest/install.html#windows

.. |weasyprint-windows| replace:: Windows

.. _sphinx-material: https://github.com/bashtage/sphinx-material/

.. |sphinx-material| replace:: Sphinx-Material

.. _sphinx-immaterial: https://github.com/jbms/sphinx-immaterial/

.. |sphinx-immaterial| replace:: Sphinx-Immaterial

.. _contributing: https://isolveit.github.io/sphinx-pdf-generate/contribute.html

.. |contributing| replace:: Contribution Guidelines

.. image:: https://img.shields.io/pypi/dm/sphinx-pdf-generate.svg
   :target: https://pypi.python.org/pypi/sphinx-pdf-generate
   :alt: Downloads
.. image:: https://img.shields.io/pypi/l/sphinx-pdf-generate.svg
   :target: https://pypi.python.org/pypi/sphinx-pdf-generate
   :alt: License
.. image:: https://img.shields.io/pypi/pyversions/sphinx-pdf-generate.svg
   :target: https://pypi.python.org/pypi/sphinx-pdf-generate
   :alt: Supported versions
.. image:: https://github.com/iSOLveIT/sphinx-pdf-generate/actions/workflows/main.yaml/badge.svg
   :target: https://github.com/iSOLveIT/sphinx-pdf-generate/actions/main.yaml
   :alt: GitHub Docs CI Action status
.. image:: https://github.com/iSOLveIT/sphinx-pdf-generate/actions/workflows/ci.yaml/badge.svg
   :target: https://github.com/iSOLveIT/sphinx-pdf-generate/actions
   :alt: GitHub CI Action status
.. image:: https://img.shields.io/pypi/v/sphinx-pdf-generate.svg
   :target: https://pypi.python.org/pypi/sphinx-pdf-generate
   :alt: PyPI Package latest release
.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
   :target: https://github.com/psf/black
   :alt: black code style

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 <http://weasyprint.org/>`_.

The extension supports many advanced features such as table of contents, customisable cover page
, support for CSS paged media module `CSS paged media module <https://developer.mozilla.org/en-US/docs/Web/CSS/@page>`_
, and using Sphinx page metadata to generate cover page.

If you find Sphinx-PDF Generate useful, please consider `starring  <https://github.com/iSOLveIT/sphinx-pdf-generate>`_ 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:
    - |weasyprint-linux|_
    - |weasyprint-macos|_
    - |weasyprint-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
++++++++++++++++++++++++++++

.. code-block:: bash

    pip install sphinx-pdf-generate


Install from source repository
++++++++++++++++++++++++++++++

.. code-block:: bash

    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 <https://isolveit.github.io/sphinx-pdf-generate/install.html>`_ page for information.

Activate Extension
------------------

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

.. code-block:: python

    extensions = ["sphinx_pdf_generate"]

You can then set the appropriate extension configuration. Visit the `options <https://isolveit.github.io/sphinx-pdf-generate/options.html>`_  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:

.. code-block:: bash

    $ 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:

.. code-block:: bash

    [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 <https://isolveit.github.io/sphinx-pdf-generate/quickstart.html>`_ 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 |contributing|_.

Special thanks
--------------

Many thanks to `Terry Zhao <https://github.com/zhaoterryy>`_ the author of the `MkDocs PDF Export Plugin <https://github.com/zhaoterryy/mkdocs-pdf-export-plugin>`_ and `Jonathan  Stoppani <https://github.com/GaretJax>`_ the author of the `Sphinx-Autobuild Plugin <https://github.com/executablebooks/sphinx-autobuild>`_.

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


