xhtml2pdf 0.2.23__tar.gz → 0.2.25__tar.gz

{xhtml2pdf-0.2.23/xhtml2pdf.egg-info → xhtml2pdf-0.2.25}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xhtml2pdf
-Version: 0.2.23
+Version: 0.2.25
 Summary: PDF generator using HTML and CSS
 Author-email: Dirk Holtwick <dirk.holtwick@gmail.com>
 Maintainer-email: Luis Zarate <luisza14@gmail.com>, Timo Brembeck <opensource@timo.brembeck.email>
@@ -246,17 +246,20 @@ License-File: AUTHORS.rst
 Requires-Dist: arabic-reshaper>=3.0.0
 Requires-Dist: html5lib>=1.1
 Requires-Dist: Pillow>=8.1.1
-Requires-Dist: pyHanko>=0.12.1
-Requires-Dist: pyhanko-certvalidator>=0.19.5
 Requires-Dist: pypdf>=3.1.0
-Requires-Dist: python-bidi>=0.5.0
 Requires-Dist: reportlab<6,>=4.4.9
 Requires-Dist: svglib>=1.2.1
+Provides-Extra: signing
+Requires-Dist: pyHanko>=0.37.0; extra == "signing"
+Requires-Dist: pyhanko-certvalidator>=0.32.1; extra == "signing"
+Provides-Extra: all
+Requires-Dist: xhtml2pdf[signing]; extra == "all"
 Provides-Extra: pycairo
 Requires-Dist: reportlab[pycairo]<6,>=4.4.9; extra == "pycairo"
 Provides-Extra: renderpm
 Requires-Dist: xhtml2pdf[pycairo]; extra == "renderpm"
 Provides-Extra: test
+Requires-Dist: xhtml2pdf[signing]; extra == "test"
 Requires-Dist: tomli>=2.0.1; python_version < "3.11" and extra == "test"
 Requires-Dist: tox; extra == "test"
 Requires-Dist: coverage>=5.3; extra == "test"
@@ -276,6 +279,9 @@ Dynamic: license-file
 XHTML2PDF
 =========
 
+**Write the document in HTML and CSS. Get a PDF.** Pure Python on top of
+ReportLab, with no browser to install or keep running.
+
 .. image:: https://img.shields.io/pypi/v/xhtml2pdf?label=PyPI&logo=PyPI&logoColor=white&color=blue
     :target: https://pypi.python.org/pypi/xhtml2pdf
     :alt: PyPI version
@@ -304,152 +310,240 @@ XHTML2PDF
    :target: http://xhtml2pdf.readthedocs.io/en/latest/?badge=latest
    :alt: Read the Docs
 
-|
-
-Release Notes can be found here: `Release Notes <https://xhtml2pdf.readthedocs.io/en/latest/release-notes.html>`__
-As with all open-source software, its use in production depends on many factors, so be aware that you may find issues in some cases.
+xhtml2pdf turns HTML5 and CSS into PDF on top of the ReportLab toolkit. Anyone
+who can build a web page can build an invoice, a report, a ticket or a book
+with it, from a Django or Flask template or from a plain string, and render
+it anywhere Python runs.
 
-**Big thanks** to everyone who has worked on this project so far and to those who help maintain it.
+Made with xhtml2pdf
+===================
 
-About
-=====
+Every page below is an HTML document converted by xhtml2pdf, fonts, charts,
+barcodes and all.
 
-xhtml2pdf is a HTML to PDF converter using Python, the ReportLab Toolkit, html5lib and pypdf. It supports HTML5 and CSS 2.1 (and some of CSS 3). It is completely written in pure Python, so it is platform independent.
+.. |annual-report| image:: https://raw.githubusercontent.com/xhtml2pdf/xhtml2pdf/master/docs/source/_static/readme/annual-report.png
+   :width: 180px
+   :alt: An annual report with a cover photo, key figures and charts
 
-The main benefit of this tool is that a user with web skills like HTML and CSS is able to generate PDF templates very quickly without learning new technologies.
+.. |invoice| image:: https://raw.githubusercontent.com/xhtml2pdf/xhtml2pdf/master/docs/source/_static/readme/invoice.png
+   :width: 180px
+   :alt: An invoice with a long table of line items and totals
 
-Please consider support this project using `Patreon <https://www.patreon.com/xhtml2pdf>`__ or Bitcoins: ``bc1qmr0skzwx5scyvh2ql28f7gfh6l65ua250qv227``
+.. |book| image:: https://raw.githubusercontent.com/xhtml2pdf/xhtml2pdf/master/docs/source/_static/readme/book.png
+   :width: 180px
+   :alt: The cover of a novella, a full-page illustration with the title
 
+.. |poster| image:: https://raw.githubusercontent.com/xhtml2pdf/xhtml2pdf/master/docs/source/_static/readme/poster.png
+   :width: 180px
+   :alt: A concert poster with a city skyline and a strip of dates
 
+.. |certificate| image:: https://raw.githubusercontent.com/xhtml2pdf/xhtml2pdf/master/docs/source/_static/readme/certificate.png
+   :width: 180px
+   :alt: A certificate of completion in landscape with a QR code
 
-Documentation
-==============
+.. |receipt-pos| image:: https://raw.githubusercontent.com/xhtml2pdf/xhtml2pdf/master/docs/source/_static/readme/receipt-pos.png
+   :width: 180px
+   :alt: A narrow point-of-sale receipt in a monospaced font
 
-The documentation of xhtml2pdf is available at `Read the Docs <http://xhtml2pdf.readthedocs.io>`__.
+.. |boarding-pass| image:: https://raw.githubusercontent.com/xhtml2pdf/xhtml2pdf/master/docs/source/_static/readme/boarding-pass.png
+   :width: 180px
+   :alt: An airline boarding pass with a barcode and a QR code
 
-And we could use your help improving it! A good place to start is ``doc/source/usage.rst``.
+.. |event-ticket| image:: https://raw.githubusercontent.com/xhtml2pdf/xhtml2pdf/master/docs/source/_static/readme/event-ticket.png
+   :width: 180px
+   :alt: A concert ticket with a stub and a barcode
 
++-----------------+-----------------+-----------------+-----------------+
+| |annual-report| | |invoice|       | |book|          | |poster|        |
++-----------------+-----------------+-----------------+-----------------+
+| |certificate|   | |receipt-pos|   | |boarding-pass| | |event-ticket|  |
++-----------------+-----------------+-----------------+-----------------+
 
-Installation
-============
+Quick start
+===========
 
-This is a typical Python library and can be installed using pip::
-
-    pip install xhtml2pdf
+.. code:: bash
 
+    pip install xhtml2pdf[all]
 
-Requirements
-============
+.. code:: python
 
-Only Python 3.10+ is tested and guaranteed to work.
+    from xhtml2pdf import pisa
 
-All mandatory requirements are listed in the ``pyproject.toml`` file and are installed automatically using the ``pip install xhtml2pdf`` method.
+    html = """
+    <style>
+      @page { size: a4; margin: 2cm;
+              @frame footer { -pdf-frame-content: footer; bottom: 1cm;
+                              margin-left: 2cm; margin-right: 2cm; height: 1cm } }
+      h1 { color: #204a87 }
+    </style>
+    <h1>Hello, PDF</h1>
+    <p>Written in HTML, laid out by CSS.</p>
+    <div id="footer">Page <pdf:pagenumber /> of <pdf:pagecount /></div>
+    """
 
-As PDF library we depend on reportlab, which needs a rendering backend to generate bitmaps and vector graphic formats.
-For more information about this, have a look at the `reportlab docs <https://docs.reportlab.com/install/open_source_installation/>`__.
+    with open("hello.pdf", "wb") as output:
+        result = pisa.CreatePDF(html, dest=output)
+    print("errors:", result.err)
 
-The recommended choice is the `cairo graphics library <https://cairographics.org/>`__ which has to be installed system-wide e.g. via the OS package manager
-in combination with the ``PyCairo`` extra dependency:
+Or from the command line:
 
-    pip install xhtml2pdf[pycairo]
+.. code:: bash
 
-The ``renderpm`` extra is a deprecated alias for ``pycairo``. ReportLab 5 removed
-the C ``RenderPM`` backend, so ``pycairo`` is now the only backend.
+    xhtml2pdf report.html report.pdf
 
+What it can do
+==============
 
-Alternatives
-============
+**Layout**
 
-You can try `WeasyPrint <http://weasyprint.org>`__. The codebase is pretty, it has different features and it does a lot of what xhtml2pdf does.
+* Flexbox (``display: flex``), including containers that break across
+  pages, and ``display: inline-block``.
+* ``position: relative``, ``absolute`` and ``fixed``, with ``z-index``.
+* Block boxes with padding, borders and backgrounds around everything they
+  hold, ``border-radius`` on blocks, tables, cells, images and inline
+  boxes, and dashed, dotted and double borders.
+* Tables with header rows repeated on every page, ``colspan`` and
+  ``rowspan``, auto margins and widths, and rows taller than a page cut
+  between pages.
+* Word breaking with ``overflow-wrap``, ``page-break-before``/``after``,
+  ``page-break-inside: avoid`` and keeping a heading with what follows.
 
+**CSS**
 
-Call for testing
-================
+* Selectors up to Level 4: ``:not()``, ``:is()``, ``:where()``, ``:has()``,
+  ``:nth-child()`` and attribute selectors.
+* Custom properties with ``var()``, ``em``/``rem``/percent units, and colours
+  with an alpha channel.
+* ``@font-face`` with TrueType and OpenType fonts, matched per character, so
+  a paragraph that mixes scripts finds a font for each of them.
 
-This project is heavily dependent on getting its test coverage up! Furthermore, parts of the codebase could do well with cleanups and refactoring.
+**Pages**
 
-If you benefit from xhtml2pdf, perhaps look at the `test coverage <https://coveralls.io/github/xhtml2pdf/xhtml2pdf>`__ and identify parts that are yet untouched.
+* ``@page`` sizes and margins, named page templates and left/right pages,
+  background images, and frames for headers, footers and columns.
+* Page numbers and page counts, watermarks and backgrounds from an image or
+  another PDF.
 
+**Navigation**
 
-Development environment
-=======================
+* Tables of contents with dot leaders, more than one per document,
+  clickable entries and a PDF outline (bookmarks).
+* Links to any element by ``id``, to other files and to the web.
 
-#. If you don't have it, install ``pip``, the python package installer::
+**International text**
 
-    sudo easy_install pip
+* Right-to-left documents in Arabic, Hebrew, Persian and Urdu, laid out with
+  a pure-Python implementation of the Unicode Bidirectional Algorithm that
+  passes the whole of the Unicode conformance suites.
+* Chinese, Japanese and Korean, Cyrillic and Greek, with the document's
+  language written to the PDF.
 
-   For more information about ``pip`` refer to http://www.pip-installer.org
+**Graphics and PDF features**
 
-#. We will recommend using ``venv`` for development.
+* SVG images, bar, line and pie charts, and barcodes and QR codes.
+* Fillable form fields, encryption with passwords and permissions, and
+  digital signatures (simple and PAdES) through pyHanko.
 
-#. ``make devsetup`` automates the steps below: it creates ``.venv``, installs
-   xhtml2pdf in editable mode with the ``test``, ``docs`` and ``release``
-   extras (the latter brings in ``build`` and ``twine``), and installs the
-   pre-commit hooks. Run it and skip to activating the environment::
+**Safe by default**
 
-    make devsetup
-    source .venv/bin/activate
+* A document cannot read local files outside its directory or reach
+  internal network addresses, and ``ResourceAccessPolicy.server()`` adds
+  limits on size, nesting and time for HTML from untrusted sources. See
+  `Security <https://xhtml2pdf.readthedocs.io/en/latest/security.html>`__.
 
-   Or do it by hand:
+Documentation
+=============
 
-#. Create a virtual environment for the project. This can be inside the project directory, but cannot be under version control::
+The documentation is on `Read the Docs <http://xhtml2pdf.readthedocs.io>`__,
+and what changed in each version is in the `Release Notes
+<https://xhtml2pdf.readthedocs.io/en/latest/release-notes.html>`__. Help
+improving it is welcome; a good place to start is
+``docs/source/quickstart.rst``.
 
-    python -m venv .venv
+Installation
+============
 
-#. Activate your virtual environment::
+.. code:: bash
 
-    source .venv/bin/activate
+    pip install xhtml2pdf[all]
 
-   Later to deactivate it use::
+Python 3.10 and newer is tested and supported. Every mandatory requirement is
+listed in ``pyproject.toml`` and installed with xhtml2pdf; ``all`` adds the
+optional ones: pyHanko, for digital signatures, which is also the
+``signing`` extra on its own. ``pip install xhtml2pdf`` leaves it out:
+asking for a signature then raises an ``ImportError`` that names the extra.
 
-    deactivate
+ReportLab needs a rendering backend to turn vector graphics into bitmaps (for
+charts and SVG rasterised into the page). The supported one is `cairo
+<https://cairographics.org/>`__, installed system-wide, for example through
+the OS package manager, together with the ``pycairo`` extra:
 
-#. The next step will be to install/upgrade dependencies from the ``pyproject.toml`` file::
+.. code:: bash
 
-    pip install -e .[test,docs,release]
+    pip install xhtml2pdf[pycairo]
 
-#. Run tests to check your configuration::
+The ``renderpm`` extra is a deprecated alias for ``pycairo``: ReportLab 5
+removed the C ``RenderPM`` backend. See the `ReportLab installation notes
+<https://docs.reportlab.com/install/open_source_installation/>`__.
 
-    tox
+Development environment
+=======================
 
-   You should have a log with the following success status::
+``make devsetup`` creates ``.venv``, installs xhtml2pdf in editable mode with
+the ``test``, ``docs`` and ``release`` extras and installs the pre-commit
+hooks:
 
-    congratulations :) (75.67 seconds)
+.. code:: bash
 
+    make devsetup
+    source .venv/bin/activate
 
-Python integration
-==================
+Or by hand:
 
-Some simple demos of how to integrate xhtml2pdf into a Python program may be found here: ``test/simple.py``
+.. code:: bash
 
+    python -m venv .venv
+    source .venv/bin/activate
+    pip install -e .[test,docs,release]
 
 Running tests
 =============
 
-Two different test suites are available to assert that xhtml2pdf works reliably:
-
-#. Unit tests. The unit testing framework is currently minimal, but is being
-   improved on a regular basis (contributions welcome). They should run in the
-   expected way for Python's unittest module, i.e.::
+.. code:: bash
 
-        tox
+    make test               # unit tests
+    make test-ref           # reference renders for testrender
+    make test-render        # compare the renders against the reference
+    make test-browser       # compare against a headless browser's rendering
+    make test-all           # every supported Python and ReportLab, with tox
 
-#. Functional tests. Thanks to mawe42's super cool work, a full functional
-   test suite is available at ``testrender/``.
+``testrender/`` renders a set of documents and compares the pages; the
+browser comparison scores xhtml2pdf against Chrome on the same markup, so a
+change that moves a layout away from a browser's shows up as a regression.
+``tools/perf`` measures time and memory.
 
-You can run them using make
+Contributing
+============
 
-.. code:: bash
+This project is community-led. Ideas, bug reports with a small HTML that
+shows the problem, and pull requests are welcome on GitHub. If xhtml2pdf is
+useful to you, look at the `test coverage
+<https://coveralls.io/github/xhtml2pdf/xhtml2pdf>`__ for parts that are not
+yet tested.
 
-        make test       # run tests
-        make test-ref   # generate reference data for testrender
-        make test-all   # Run all test using tox
+You can also support the project on `Patreon
+<https://www.patreon.com/xhtml2pdf>`__ or with Bitcoin:
+``bc1qmr0skzwx5scyvh2ql28f7gfh6l65ua250qv227``.
 
-Contact
-=======
+**Big thanks** to everyone who has worked on this project so far and to those
+who help maintain it.
 
-This project is community-led! Feel free to open up issues on GitHub about new ideas to improve xhtml2pdf.
+Alternatives
+============
 
+`WeasyPrint <http://weasyprint.org>`__ covers much of the same ground with a
+different design and set of features.
 
 History
 =======

xhtml2pdf-0.2.25/README.rst

@@ -0,0 +1,298 @@
+XHTML2PDF
+=========
+
+**Write the document in HTML and CSS. Get a PDF.** Pure Python on top of
+ReportLab, with no browser to install or keep running.
+
+.. image:: https://img.shields.io/pypi/v/xhtml2pdf?label=PyPI&logo=PyPI&logoColor=white&color=blue
+    :target: https://pypi.python.org/pypi/xhtml2pdf
+    :alt: PyPI version
+
+.. image:: https://img.shields.io/pypi/pyversions/xhtml2pdf?label=Python&logo=Python&logoColor=white
+    :target: https://www.python.org/downloads
+    :alt: Python versions
+
+.. image:: https://img.shields.io/github/actions/workflow/status/xhtml2pdf/xhtml2pdf/tests.yml?branch=master&label=Tests&logo=github&logoColor=white
+    :target: https://github.com/xhtml2pdf/xhtml2pdf/actions/workflows/tests.yml
+    :alt: Tests
+
+.. image:: https://img.shields.io/github/actions/workflow/status/xhtml2pdf/xhtml2pdf/linting.yml?branch=master&label=Linting&logo=github&logoColor=white
+    :target: https://github.com/xhtml2pdf/xhtml2pdf/actions/workflows/linting.yml
+    :alt: Linting
+
+.. image:: https://img.shields.io/github/actions/workflow/status/xhtml2pdf/xhtml2pdf/spelling.yml?branch=master&label=Spelling&logo=github&logoColor=white
+    :target: https://github.com/xhtml2pdf/xhtml2pdf/actions/workflows/spelling.yml
+    :alt: Spelling
+
+.. image:: https://img.shields.io/coveralls/github/xhtml2pdf/xhtml2pdf?label=Coveralls&logo=Coveralls&logoColor=white
+    :target: https://coveralls.io/github/xhtml2pdf/xhtml2pdf
+    :alt: Coveralls
+
+.. image:: https://img.shields.io/readthedocs/xhtml2pdf?label=Read%20the%20Docs&logo=read%20the%20docs&logoColor=white
+   :target: http://xhtml2pdf.readthedocs.io/en/latest/?badge=latest
+   :alt: Read the Docs
+
+xhtml2pdf turns HTML5 and CSS into PDF on top of the ReportLab toolkit. Anyone
+who can build a web page can build an invoice, a report, a ticket or a book
+with it, from a Django or Flask template or from a plain string, and render
+it anywhere Python runs.
+
+Made with xhtml2pdf
+===================
+
+Every page below is an HTML document converted by xhtml2pdf, fonts, charts,
+barcodes and all.
+
+.. |annual-report| image:: https://raw.githubusercontent.com/xhtml2pdf/xhtml2pdf/master/docs/source/_static/readme/annual-report.png
+   :width: 180px
+   :alt: An annual report with a cover photo, key figures and charts
+
+.. |invoice| image:: https://raw.githubusercontent.com/xhtml2pdf/xhtml2pdf/master/docs/source/_static/readme/invoice.png
+   :width: 180px
+   :alt: An invoice with a long table of line items and totals
+
+.. |book| image:: https://raw.githubusercontent.com/xhtml2pdf/xhtml2pdf/master/docs/source/_static/readme/book.png
+   :width: 180px
+   :alt: The cover of a novella, a full-page illustration with the title
+
+.. |poster| image:: https://raw.githubusercontent.com/xhtml2pdf/xhtml2pdf/master/docs/source/_static/readme/poster.png
+   :width: 180px
+   :alt: A concert poster with a city skyline and a strip of dates
+
+.. |certificate| image:: https://raw.githubusercontent.com/xhtml2pdf/xhtml2pdf/master/docs/source/_static/readme/certificate.png
+   :width: 180px
+   :alt: A certificate of completion in landscape with a QR code
+
+.. |receipt-pos| image:: https://raw.githubusercontent.com/xhtml2pdf/xhtml2pdf/master/docs/source/_static/readme/receipt-pos.png
+   :width: 180px
+   :alt: A narrow point-of-sale receipt in a monospaced font
+
+.. |boarding-pass| image:: https://raw.githubusercontent.com/xhtml2pdf/xhtml2pdf/master/docs/source/_static/readme/boarding-pass.png
+   :width: 180px
+   :alt: An airline boarding pass with a barcode and a QR code
+
+.. |event-ticket| image:: https://raw.githubusercontent.com/xhtml2pdf/xhtml2pdf/master/docs/source/_static/readme/event-ticket.png
+   :width: 180px
+   :alt: A concert ticket with a stub and a barcode
+
++-----------------+-----------------+-----------------+-----------------+
+| |annual-report| | |invoice|       | |book|          | |poster|        |
++-----------------+-----------------+-----------------+-----------------+
+| |certificate|   | |receipt-pos|   | |boarding-pass| | |event-ticket|  |
++-----------------+-----------------+-----------------+-----------------+
+
+Quick start
+===========
+
+.. code:: bash
+
+    pip install xhtml2pdf[all]
+
+.. code:: python
+
+    from xhtml2pdf import pisa
+
+    html = """
+    <style>
+      @page { size: a4; margin: 2cm;
+              @frame footer { -pdf-frame-content: footer; bottom: 1cm;
+                              margin-left: 2cm; margin-right: 2cm; height: 1cm } }
+      h1 { color: #204a87 }
+    </style>
+    <h1>Hello, PDF</h1>
+    <p>Written in HTML, laid out by CSS.</p>
+    <div id="footer">Page <pdf:pagenumber /> of <pdf:pagecount /></div>
+    """
+
+    with open("hello.pdf", "wb") as output:
+        result = pisa.CreatePDF(html, dest=output)
+    print("errors:", result.err)
+
+Or from the command line:
+
+.. code:: bash
+
+    xhtml2pdf report.html report.pdf
+
+What it can do
+==============
+
+**Layout**
+
+* Flexbox (``display: flex``), including containers that break across
+  pages, and ``display: inline-block``.
+* ``position: relative``, ``absolute`` and ``fixed``, with ``z-index``.
+* Block boxes with padding, borders and backgrounds around everything they
+  hold, ``border-radius`` on blocks, tables, cells, images and inline
+  boxes, and dashed, dotted and double borders.
+* Tables with header rows repeated on every page, ``colspan`` and
+  ``rowspan``, auto margins and widths, and rows taller than a page cut
+  between pages.
+* Word breaking with ``overflow-wrap``, ``page-break-before``/``after``,
+  ``page-break-inside: avoid`` and keeping a heading with what follows.
+
+**CSS**
+
+* Selectors up to Level 4: ``:not()``, ``:is()``, ``:where()``, ``:has()``,
+  ``:nth-child()`` and attribute selectors.
+* Custom properties with ``var()``, ``em``/``rem``/percent units, and colours
+  with an alpha channel.
+* ``@font-face`` with TrueType and OpenType fonts, matched per character, so
+  a paragraph that mixes scripts finds a font for each of them.
+
+**Pages**
+
+* ``@page`` sizes and margins, named page templates and left/right pages,
+  background images, and frames for headers, footers and columns.
+* Page numbers and page counts, watermarks and backgrounds from an image or
+  another PDF.
+
+**Navigation**
+
+* Tables of contents with dot leaders, more than one per document,
+  clickable entries and a PDF outline (bookmarks).
+* Links to any element by ``id``, to other files and to the web.
+
+**International text**
+
+* Right-to-left documents in Arabic, Hebrew, Persian and Urdu, laid out with
+  a pure-Python implementation of the Unicode Bidirectional Algorithm that
+  passes the whole of the Unicode conformance suites.
+* Chinese, Japanese and Korean, Cyrillic and Greek, with the document's
+  language written to the PDF.
+
+**Graphics and PDF features**
+
+* SVG images, bar, line and pie charts, and barcodes and QR codes.
+* Fillable form fields, encryption with passwords and permissions, and
+  digital signatures (simple and PAdES) through pyHanko.
+
+**Safe by default**
+
+* A document cannot read local files outside its directory or reach
+  internal network addresses, and ``ResourceAccessPolicy.server()`` adds
+  limits on size, nesting and time for HTML from untrusted sources. See
+  `Security <https://xhtml2pdf.readthedocs.io/en/latest/security.html>`__.
+
+Documentation
+=============
+
+The documentation is on `Read the Docs <http://xhtml2pdf.readthedocs.io>`__,
+and what changed in each version is in the `Release Notes
+<https://xhtml2pdf.readthedocs.io/en/latest/release-notes.html>`__. Help
+improving it is welcome; a good place to start is
+``docs/source/quickstart.rst``.
+
+Installation
+============
+
+.. code:: bash
+
+    pip install xhtml2pdf[all]
+
+Python 3.10 and newer is tested and supported. Every mandatory requirement is
+listed in ``pyproject.toml`` and installed with xhtml2pdf; ``all`` adds the
+optional ones: pyHanko, for digital signatures, which is also the
+``signing`` extra on its own. ``pip install xhtml2pdf`` leaves it out:
+asking for a signature then raises an ``ImportError`` that names the extra.
+
+ReportLab needs a rendering backend to turn vector graphics into bitmaps (for
+charts and SVG rasterised into the page). The supported one is `cairo
+<https://cairographics.org/>`__, installed system-wide, for example through
+the OS package manager, together with the ``pycairo`` extra:
+
+.. code:: bash
+
+    pip install xhtml2pdf[pycairo]
+
+The ``renderpm`` extra is a deprecated alias for ``pycairo``: ReportLab 5
+removed the C ``RenderPM`` backend. See the `ReportLab installation notes
+<https://docs.reportlab.com/install/open_source_installation/>`__.
+
+Development environment
+=======================
+
+``make devsetup`` creates ``.venv``, installs xhtml2pdf in editable mode with
+the ``test``, ``docs`` and ``release`` extras and installs the pre-commit
+hooks:
+
+.. code:: bash
+
+    make devsetup
+    source .venv/bin/activate
+
+Or by hand:
+
+.. code:: bash
+
+    python -m venv .venv
+    source .venv/bin/activate
+    pip install -e .[test,docs,release]
+
+Running tests
+=============
+
+.. code:: bash
+
+    make test               # unit tests
+    make test-ref           # reference renders for testrender
+    make test-render        # compare the renders against the reference
+    make test-browser       # compare against a headless browser's rendering
+    make test-all           # every supported Python and ReportLab, with tox
+
+``testrender/`` renders a set of documents and compares the pages; the
+browser comparison scores xhtml2pdf against Chrome on the same markup, so a
+change that moves a layout away from a browser's shows up as a regression.
+``tools/perf`` measures time and memory.
+
+Contributing
+============
+
+This project is community-led. Ideas, bug reports with a small HTML that
+shows the problem, and pull requests are welcome on GitHub. If xhtml2pdf is
+useful to you, look at the `test coverage
+<https://coveralls.io/github/xhtml2pdf/xhtml2pdf>`__ for parts that are not
+yet tested.
+
+You can also support the project on `Patreon
+<https://www.patreon.com/xhtml2pdf>`__ or with Bitcoin:
+``bc1qmr0skzwx5scyvh2ql28f7gfh6l65ua250qv227``.
+
+**Big thanks** to everyone who has worked on this project so far and to those
+who help maintain it.
+
+Alternatives
+============
+
+`WeasyPrint <http://weasyprint.org>`__ covers much of the same ground with a
+different design and set of features.
+
+History
+=======
+
+These are the major milestones and the maintainers of the project:
+
+* 2000-2007 Dirk Holtwick (commercial project of spirito.de)
+* 2007-2010 Dirk Holtwick (project named "pisa", project released as GPL)
+* 2010-2012 Dirk Holtwick (project named "xhtml2pdf", changed license to Apache)
+* 2012-2015 Chris Glass (@chrisglass)
+* 2015-2016 Benjamin Bach (@benjaoming)
+* 2016-2018 Sam Spencer (@LegoStormtroopr)
+* 2018-Current Luis Zarate (@luisza)
+
+For more history, see the `Release Notes <https://xhtml2pdf.readthedocs.io/en/latest/release-notes.html>`__.
+
+License
+=======
+
+Copyright 2010 Dirk Holtwick, holtwick.it
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at: http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.