Add more common use cases in documentation
This commit is contained in:
Guillaume Ayoub
+7
-16
@@ -149,7 +149,7 @@ PDF
|
||||
~~~
|
||||
|
||||
In addition to text, raster and vector graphics, WeasyPrint’s PDF files
|
||||
can contain hyperlinks, bookmarks and attachments.
|
||||
can contain hyperlinks, bookmarks, attachments and forms.
|
||||
|
||||
Hyperlinks will be clickable in PDF viewers that support them. They can
|
||||
be either internal, to another part of the same document (eg.
|
||||
@@ -169,22 +169,13 @@ or through regular links with ``<a rel=attachment>`` to attach a resource that
|
||||
can be saved by clicking on said link. The ``title`` attribute can be used as
|
||||
description of the attachment.
|
||||
|
||||
The generation of PDF/A documents (A-1b, A-2b, A-3b, A-4b, A-2u, A-3u and A-4u) is
|
||||
supported. However, the generated documents are not guaranteed to be valid, and users
|
||||
have the responsibility to check that they follow the rules listed by the related
|
||||
specifications. The major rules to follow are to include a PDF identifier, to check the
|
||||
PDF version, and to avoid anti-aliasing for images using ``image-rendering:
|
||||
crisp-edges``.
|
||||
Generated documents can also include PDF forms, using the ``appearance: auto``
|
||||
CSS property or the ``--pdf-forms`` CLI option.
|
||||
|
||||
The generation of PDF/UA documents (UA-1) is supported. However, the generated
|
||||
documents are not guaranteed to be valid, and users have the responsibility to
|
||||
check that they follow the rules listed by the related specifications. The main
|
||||
constraint is to use a correct HTML structure to avoid inconsistencies in the
|
||||
PDF structure.
|
||||
|
||||
Generated PDFs can include forms, using the ``appearance: auto`` CSS property
|
||||
or the ``--pdf-forms`` CLI option. Text inputs, text areas and check boxes are
|
||||
supported.
|
||||
The generation of PDF/A and PDF/UA documents is supported. However, the
|
||||
generated documents are not guaranteed to be valid, and users have the
|
||||
responsibility to check that they follow the rules listed by the related
|
||||
specifications.
|
||||
|
||||
|
||||
Fonts
|
||||
|
||||
+268
-2
@@ -102,6 +102,238 @@ such as page numbers, headers, etc. Read more about the page_ at-rule.
|
||||
.. _page: https://developer.mozilla.org/en-US/docs/Web/CSS/@page
|
||||
|
||||
|
||||
Generate PDFs Specialized for Accessibility (PDF/UA) and Archiving (PDF/A)
|
||||
--------------------------------------------------------------------------
|
||||
|
||||
WeasyPrint can generate different PDF variants, including PDF/UA and PDF/A. The
|
||||
feature is available by using the ``--pdf-variant`` CLI option, or the
|
||||
``pdf_variant`` Python parameter of :func:`HTML.write_pdf
|
||||
<weasyprint.HTML.write_pdf>`.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from weasyprint import HTML
|
||||
HTML(string="<p>document</p>").write_pdf("document.pdf", pdf_variant="pdf/a-3u")
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
$ weasyprint document.html --pdf-variant="pdf/ua-1" document.pdf
|
||||
|
||||
The different supported variants can be listed using ``weasyprint --help``.
|
||||
|
||||
Even if WeasyPrint tries to generate valid documents, the result is not
|
||||
guaranteed: the HTML, CSS and PDF features chosen by the user must follow the
|
||||
limitations defined by the different specifications.
|
||||
|
||||
PDF/A
|
||||
.....
|
||||
|
||||
PDF/A documents are specialized for archiving purposes. They are a simple
|
||||
subset of PDF, with a lot of limitations: no audio, video or JavaScript,
|
||||
defined color spaces, embedded fonts, etc.
|
||||
|
||||
If possible, PDF/A-3u should be preferred: it allows transparency layers that
|
||||
are forbidden in A-1, and arbitrary formats for attached files that are
|
||||
forbidden in A-2. The "u" part of the variant indicates that the PDF text is
|
||||
available as Unicode.
|
||||
|
||||
PDF/A documents include a PDF identifier, that is mainly useful to indicate
|
||||
that a PDF is a new version of another PDF. By default, WeasyPrint generates a
|
||||
valid PDF identifier, but you can provide your own with the
|
||||
``--pdf-identifier`` CLI option or ``pdf_identifier`` Python parameter.
|
||||
|
||||
If your document includes images, you must set the ``image-rendering:
|
||||
crisp-edges`` property to avoid anti-aliasing, that is forbidden by PDF/A.
|
||||
|
||||
PDF/UA
|
||||
......
|
||||
|
||||
PDF/UA documents are specialized for accessibility purposes. They include extra
|
||||
metadata that define document information and content structure.
|
||||
|
||||
The main constraint to get valid PDF/UA documents is to use a correct HTML
|
||||
structure, to avoid inconsistencies in the PDF structure. The HTML order is
|
||||
also used to define the order of the PDF content.
|
||||
|
||||
Some information is required in your HTML file, including a ``<title>`` tag,
|
||||
and a ``lang`` attribute set on the ``<html>`` tag.
|
||||
|
||||
|
||||
Include PDF Forms
|
||||
-----------------
|
||||
|
||||
By default, form fields are transformed into pure text and graphical shapes
|
||||
when exported to PDF. But WeasyPrint gives the possibility to generate real PDF
|
||||
forms that can be filled with a PDF reader. These forms can even send requests
|
||||
with the data filled in the PDF, just as the same form would do in a web
|
||||
browser.
|
||||
|
||||
To transform all HTML forms into PDF forms, you can use the ``--pdf-forms`` CLI
|
||||
option or ``pdf_forms`` Python parameter.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from weasyprint import HTML
|
||||
HTML(string="<input value='test'>").write_pdf("test.pdf", pdf_forms=True)
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
$ weasyprint document.html --pdf-forms document.pdf
|
||||
|
||||
You can also define which specific fields (``input``, ``select``, ``textarea``,
|
||||
``button``) have to be transformed into PDF forms by setting the ``appearance``
|
||||
CSS property to ``auto`` on them. In this case, as for browsers, you’ll have to
|
||||
manually override the default style set by the user agent stylesheet. Reading
|
||||
`the stylesheet set by the --pdf-forms option
|
||||
<https://github.com/Kozea/WeasyPrint/blob/main/weasyprint/css/html5_ua_form.css>`_
|
||||
can help to override this style.
|
||||
|
||||
.. code-block:: html
|
||||
|
||||
<style>
|
||||
label { display: block }
|
||||
.pdf-form { appearance: auto }
|
||||
.pdf-form::before { visibility: hidden }
|
||||
</style>
|
||||
<label>
|
||||
Can't be modified in PDF
|
||||
<input value="static">
|
||||
</label>
|
||||
<label>
|
||||
Can be modified in PDF
|
||||
<input class="pdf-form" value="dynamic">
|
||||
</label>
|
||||
|
||||
PDF forms support can be quite poor depending on the PDF reader you use. If a
|
||||
feature doesn’t work for you, please check that this feature is actually
|
||||
supported by your PDF reader before reporting a bug.
|
||||
|
||||
|
||||
Define PDF Metadata
|
||||
-------------------
|
||||
|
||||
PDF documents can include various metadata, such as title, authors or creation
|
||||
date. The easiest way to define them is to include them in your HTML file:
|
||||
these fields are normalized and can be automatically picked up by WeasyPrint.
|
||||
|
||||
.. code-block:: html
|
||||
|
||||
<html lang="en">
|
||||
<head>
|
||||
<title>PDF Sample with Metadata</title>
|
||||
<meta name="author" content="Jane Doe">
|
||||
<meta name="author" content="John Doe">
|
||||
<meta name="generator" content="HTML generator">
|
||||
<meta name="keywords" content="HTML, CSS, PDF">
|
||||
<meta name="dcterms.created" content="2000-12-31T12:34:56+02:00">
|
||||
<meta name="dcterms.modified" content="2010-07-14">
|
||||
<meta name="description" content="This is a simple sample">
|
||||
</head>
|
||||
</html>
|
||||
|
||||
HTML metadata values listed here, including language and title, are stored in
|
||||
the corresponding, normalized fields in PDF.
|
||||
|
||||
If you use custom metadata fields, they are not stored in PDF by default. You
|
||||
can include them in the PDF info dictionary using the ``--custom-metadata`` CLI
|
||||
option or the ``custsom_metadata`` Python parameter.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from weasyprint import HTML
|
||||
HTML(string="<meta name="recipe" content="fries">").write_pdf("recipe.pdf", custom_metadata=True)
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
$ weasyprint document.html --custom-metadata document.pdf
|
||||
|
||||
|
||||
Attach Files
|
||||
------------
|
||||
|
||||
You can attach files to your generated PDF. These files can be opened when a
|
||||
link is clicked in the PDF, or just available in the list of attached files in
|
||||
your PDF reader.
|
||||
|
||||
To attach a file with a regular link, you can use a regular anchor with the
|
||||
``rel`` attribute set to ``attachment``.
|
||||
|
||||
.. code-block:: html
|
||||
|
||||
<a rel="attachment" href="note.txt">view attached note</a>
|
||||
|
||||
To attach a file globally to the document, you can add a ``link`` tag in your
|
||||
``head``:
|
||||
|
||||
.. code-block:: html
|
||||
|
||||
<link rel="attachment" href="note.txt">
|
||||
|
||||
If you don’t want to attach your files using HTML tags, you can also use the
|
||||
``--attachment`` CLI option, multiple times if needed.
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
$ weasyprint document.html --attachment note.txt --attachment photo.jpg document.pdf
|
||||
|
||||
In a Python script, you can also attach files using the
|
||||
:class:`weasyprint.Attachment` class.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from weasyprint import Attachment, HTML
|
||||
attachments = [Attachment("note.txt"), Attachment("photo.jpg")]
|
||||
HTML(string="<p>PDF with attachments</p>").write_pdf("recipe.pdf", attachments=attachments)
|
||||
|
||||
|
||||
Cache and Optimize Images
|
||||
-------------------------
|
||||
|
||||
WeasyPrint provides many options to deal with images: ``optimize_images``,
|
||||
``jpeg_quality``, ``dpi`` and ``cache``.
|
||||
|
||||
``optimize_images`` can enable size optimization for images. When enabled, the
|
||||
generated PDF will include smaller images with no quality penalty, but the
|
||||
rendering time may be slightly increased.
|
||||
|
||||
The ``jpeg_quality`` option can be set to decrease the quality of JPEG images
|
||||
included in the PDF. You can set a value between 95 (best quality) to 0
|
||||
(smaller image size), depending on your needs.
|
||||
|
||||
The ``dpi`` option offers the possibility to reduce the size (in pixels, and
|
||||
thus in bytes) of all included raster images. The resolution, set in dots per
|
||||
inch, indicates the maximum number of pixels included in one inch on the
|
||||
generated PDF.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
# Original high-quality images, faster, but generated PDF is larger
|
||||
HTML('https://weasyprint.org/').write_pdf('weasyprint.pdf')
|
||||
|
||||
# Optimized lower-quality images, a bit slower, but generated PDF is smaller
|
||||
HTML('https://weasyprint.org/').write_pdf(
|
||||
'weasyprint.pdf', optimize_images=True, jpeg_quality=60, dpi=150)
|
||||
|
||||
``cache`` gives the possibility to use a cache for images, avoiding to
|
||||
download, parse and optimize them each time they are used.
|
||||
|
||||
By default, the cache is used document by document, but you can share it
|
||||
between documents if needed. This feature can save a lot of network and CPU
|
||||
time when you render a lot of documents that use the same images.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
cache = {}
|
||||
for i in range(10):
|
||||
HTML(f'https://weasyprint.org/').write_pdf(
|
||||
f'example-{i}.pdf', cache=cache)
|
||||
|
||||
It’s also possible to cache images on disk instead of keeping them in memory.
|
||||
The ``--cache-folder`` CLI option can be used to define the folder used to
|
||||
store temporary images. You can also provide this folder path as a string for
|
||||
``cache``.
|
||||
|
||||
|
||||
Improve Rendering Speed and Memory Use
|
||||
--------------------------------------
|
||||
|
||||
@@ -119,10 +351,44 @@ Some tips may help you to get better results.
|
||||
drastically reduce the rendering time.
|
||||
- Tables are known to be slow, especially when they are rendered on multiple
|
||||
pages. When possible, using a common block layout instead gives much faster
|
||||
layouts.
|
||||
renderings.
|
||||
- Optimizing images and fonts can reduce the PDF size, but increase the
|
||||
rendering time. Moreover, caching images gives the possibility to read and
|
||||
optimize images only once, and thus to save time when the same image is used
|
||||
multiple times. See :ref:`Image Cache and Optimization`.
|
||||
multiple times. See :ref:`Cache and Optimize Images`.
|
||||
|
||||
.. _WeasyPerf: https://kozea.github.io/WeasyPerf/
|
||||
|
||||
|
||||
Show Log Messages
|
||||
-----------------
|
||||
|
||||
Most errors (unsupported CSS property, missing image…) are not fatal and will
|
||||
not prevent a document from being rendered. WeasyPrint uses the :mod:`logging`
|
||||
module from the Python standard library to log these errors and let you know
|
||||
about them.
|
||||
|
||||
When WeasyPrint is launched in a terminal, logged messages will go to the
|
||||
standard error stream (``stderr``) by default. When used as a library, logs are
|
||||
not displayed at all. You can change that by configuring the ``weasyprint``
|
||||
logger object:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
import logging
|
||||
logger = logging.getLogger('weasyprint')
|
||||
|
||||
# Display warnings, errors and critical messages.
|
||||
logger.setLevel(logging.WARNING)
|
||||
|
||||
# Save logs to the weasyprint.log file.
|
||||
logger.addHandler(logging.FileHandler('weasyprint.log'))
|
||||
# Print logs on console.
|
||||
logger.addHandler(logging.StreamHandler())
|
||||
|
||||
The ``weasyprint.progress`` logger is used to report the rendering progress. It
|
||||
is useful to get feedback when WeasyPrint is launched in a terminal (using the
|
||||
``--verbose`` or ``--debug`` option), or to give this feedback to end users
|
||||
when used as a library.
|
||||
|
||||
See the documentation of the :mod:`logging` module for details.
|
||||
|
||||
+2
-74
@@ -426,8 +426,8 @@ file name or a writable :term:`file object`, they will write there directly
|
||||
instead. (**Warning**: with a filename, these methods will overwrite existing
|
||||
files silently.)
|
||||
|
||||
Individual Pages & Meta-Data
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
Rendering Individual Pages
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
If you want more than a single PDF, the :meth:`HTML.render` method gives you a
|
||||
:class:`document.Document` object with access to individual
|
||||
@@ -522,78 +522,6 @@ the function internally used by WeasyPrint to retrieve data.
|
||||
.. _Django-WeasyPrint: https://github.com/fdemmer/django-weasyprint
|
||||
.. _Django: https://www.djangoproject.com/
|
||||
|
||||
Image Cache and Optimization
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
WeasyPrint provides many options to deal with images: ``optimize_images``,
|
||||
``jpeg_quality``, ``dpi`` and ``cache``.
|
||||
|
||||
``optimize_images`` can enable size optimization for images. When enabled, the
|
||||
generated PDF will include smaller images with no quality penalty, but the
|
||||
rendering time may be slightly increased.
|
||||
|
||||
The ``jpeg_quality`` option can be set to decrease the quality of JPEG images
|
||||
included in the PDF. You can set a value between 95 (best quality) to 0
|
||||
(smaller image size), depending on your needs.
|
||||
|
||||
The ``dpi`` option offers the possibility to reduce the size (in pixels, and
|
||||
thus in bytes) of all included raster images. The resolution, set in dots per
|
||||
inch, indicates the maximum number of pixels included in one inch on the
|
||||
generated PDF.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
# Original high-quality images, faster, but generated PDF is larger
|
||||
HTML('https://weasyprint.org/').write_pdf('weasyprint.pdf')
|
||||
|
||||
# Optimized lower-quality images, a bit slower, but generated PDF is smaller
|
||||
HTML('https://weasyprint.org/').write_pdf(
|
||||
'weasyprint.pdf', optimize_images=True, jpeg_quality=60, dpi=150)
|
||||
|
||||
``cache`` gives the possibility to use a cache for images, avoiding to
|
||||
download, parse and optimize them each time they are used.
|
||||
|
||||
By default, the cache is used document by document, but you can share it
|
||||
between documents if needed. This feature can save a lot of network and CPU
|
||||
time when you render a lot of documents that use the same images.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
cache = {}
|
||||
for i in range(10):
|
||||
HTML(f'https://weasyprint.org/').write_pdf(
|
||||
f'example-{i}.pdf', cache=cache)
|
||||
|
||||
It’s also possible to cache images on disk instead of keeping them in memory.
|
||||
The ``--cache-folder`` CLI option can be used to define the folder used to
|
||||
store temporary images. You can also provide this folder path as a string for
|
||||
``cache``.
|
||||
|
||||
|
||||
Logging
|
||||
~~~~~~~
|
||||
|
||||
Most errors (unsupported CSS property, missing image, ...)
|
||||
are not fatal and will not prevent a document from being rendered.
|
||||
|
||||
WeasyPrint uses the :mod:`logging` module from the Python standard library to
|
||||
log these errors and let you know about them. When WeasyPrint is launched in a
|
||||
terminal, logged messaged will go to *stderr* by default. You can change that
|
||||
by configuring the ``weasyprint`` logger object:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
import logging
|
||||
logger = logging.getLogger('weasyprint')
|
||||
logger.addHandler(logging.FileHandler('/path/to/weasyprint.log'))
|
||||
|
||||
The ``weasyprint.progress`` logger is used to report the rendering progress. It
|
||||
is useful to get feedback when WeasyPrint is launched in a terminal (using the
|
||||
``--verbose`` or ``--debug`` option), or to give this feedback to end users
|
||||
when used as a library.
|
||||
|
||||
See the documentation of the :mod:`logging` module for details.
|
||||
|
||||
|
||||
Security
|
||||
--------
|
||||
|
||||
Reference in New Issue
Block a user