Metadata-Version: 2.1
Name: sphinx_pyppeteer_builder
Version: 1.0.0
Summary: A Sphinx PDF builder using pyppeteer
Keywords: sphinx,doc,pdf,pyppeteer
Author: kujiu, ptitgnu
Author-email: Nerv Project ASBL <contact@nerv-project.eu>
Maintainer: kujiu, ptitgnu
Maintainer-email: Nerv Project ASBL <contact@nerv-project.eu>
Requires-Python: >=3.8
Description-Content-Type: text/x-rst
Classifier: Framework :: Sphinx
Classifier: Framework :: Sphinx :: Extension
Classifier: Development Status :: 5 - Production/Stable
Classifier: License :: OSI Approved :: European Union Public Licence 1.2 (EUPL 1.2)
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Topic :: Documentation
Classifier: Topic :: Software Development :: Documentation
Requires-Dist: Sphinx>=7.0.0
Requires-Dist: pyppeteer
Requires-Dist: typing_extensions
Requires-Dist: Sphinx ; extra == "setup"
Requires-Dist: pytest-runner ; extra == "setup"
Requires-Dist: pyright ; extra == "setup"
Requires-Dist: pylint ; extra == "setup"
Requires-Dist: babel ; extra == "setup"
Requires-Dist: flit ; extra == "setup"
Requires-Dist: pytest ; extra == "tests"
Requires-Dist: pyright ; extra == "tests"
Requires-Dist: pylint ; extra == "tests"
Requires-Dist: pytest-cov ; extra == "tests"
Project-URL: changelog, https://procrastinator.nerv-project.eu/nerv-project/sphinx_pyppeteer_builder/raw/branch/main/CHANGES.rst
Project-URL: editor, https://www.nerv-project.eu
Project-URL: homepage, https://www.nerv-project.eu
Project-URL: issues, https://procrastinator.nerv-project.eu/nerv-project/sphinx_pyppeteer_builder/issues
Project-URL: repository, https://procrastinator.nerv-project.eu/nerv-project/sphinx_pyppeteer_builder
Provides-Extra: setup
Provides-Extra: tests

Sphinx Pyppeteer builder
========================

Sphinx Pyppeteer builder is a PDF generator for
`Sphinx <https://www.sphinx-doc.org>`_ without usage
of LaTeX. It uses `Pyppeteer <https://github.com/pyppeteer/pyppeteer>`_,
a wrapper to control a web browser. It supports
Chromium for now.

Install
-------

You can install it with `pip`:

.. code:: bash

   pip install sphinx_pyppeteer_builder

Or with `setup.py`:

.. code:: bash

   python setup.py install
   pyppeteer-install

.. important::

   Do not forget to install chromium-headless via
   pyppeteer with command `pyppeteer-install`.
   Generation will not work without that.

Configuration
-------------

You can configure your output with these options:

- pyppeteer_basename
- pyppeteer_theme
- pyppeteer_theme_options
- pyppeteer_title
- pyppeteer_theme_path
- pyppeteer_short_title
- pyppeteer_style
- pyppeteer_css_files
- pyppeteer_show_copyright
- pyppeteer_show_sphinx

Each one has the same behavior of its equivalent
for `html` builder.

.. warning::

   Some themes need adaptation to work fine with
   this module. Check your CSS.

In addition, you can set `pyppeteer_pdf_options`
var. This dict is passed as is to
`the pdf coroutine <https://pyppeteer.github.io/pyppeteer/reference.html#pyppeteer.page.Page.pdf>`_. Default values are:

.. code:: python

   pyppeteer_pdf_options = {
       'printBackground': True,
       'format': 'A4',
       'margin': {
           'top': '20mm',
           'bottom': '20mm',
           'left': '10mm',
           'right': '10mm'
       }
   }


.. warning::

   Path option in `pyppeteer_pdf_options` is ignored.

Use
---

Just launch the following:

.. code:: bash

   make pyppeteer

Why an other PDF builder for Sphinx?
------------------------------------

LaTeX is really hard to use and to personalize.
There's also an other project to make PDF without
LaTeX but it is not based on CSS stylesheets.

Web browser to generate PDF have all new generation
CSS specs implemented. You can use
`sphinx_weasyprint_builder` instead if you
don't want a full browser.

This plugin is just `singlehtml` output with
conversion to PDF.

