From ac34f547e5dca6613d1c0bfafbb22af32ee51a6f Mon Sep 17 00:00:00 2001 From: Guillaume Ayoub Date: Thu, 11 Oct 2018 11:21:02 +0200 Subject: [PATCH] Clean the hacking page of the documentation --- docs/hacking.rst | 48 +++++++++++++++++++++++------------------------- 1 file changed, 23 insertions(+), 25 deletions(-) diff --git a/docs/hacking.rst b/docs/hacking.rst index 2f05c2446..77ddbc4db 100644 --- a/docs/hacking.rst +++ b/docs/hacking.rst @@ -10,14 +10,14 @@ install the `development version`_ of WeasyPrint: git clone git://github.com/Kozea/WeasyPrint.git cd WeasyPrint - virtualenv --system-site-packages env + python3 -m venv env . env/bin/activate - pip install Sphinx -e .[test] + pip install -e .[doc,test] weasyprint --help This will install WeasyPrint in “editable” mode (which means that you don’t need to re-install it every time you make a change in the source code) as well -as `pytest `_ and `Sphinx `_. +as `pytest `_ and `Sphinx `_. Lastly, in order to pass unit tests, your system must have as default font any font with a condensed variant (i.e. DejaVu) - typically installable via your @@ -55,17 +55,15 @@ Much like `in web browsers `_, the rendering of a document in WeasyPrint goes like this: -1. The HTML document is fetched and parsed into a tree of elements (like DOM) +1. The HTML document is fetched and parsed into a tree of elements (like DOM). 2. CSS stylesheets (either found in the HTML or supplied by the user) are - fetched and parsed -3. The stylesheets are applied to the DOM tree -4. The DOM tree with styles is transformed into a *formatting structure* made of rectangular boxes. + fetched and parsed. +3. The stylesheets are applied to the DOM-like tree. +4. The DOM-like tree with styles is transformed into a *formatting structure* + made of rectangular boxes. 5. These boxes are *laid-out* with fixed dimensions and position onto pages. -6. For each page, the boxes: - - - are re-ordered to observe stacking rules, and - - are drawn on a PDF page. - +6. For each page, the boxes are re-ordered to observe stacking rules, and are + drawn on a PDF page. 7. Cairo’s PDF is modified to add metadata such as bookmarks and hyperlinks. @@ -82,6 +80,7 @@ CSS As with HTML, CSS stylesheets are parsed in the :class:`weasyprint.CSS` class with an external library, tinycss2_. + After the In addition to the actual parsing, the :mod:`weasyprint.css` and :mod:`weasyprint.css.validation` modules do some pre-processing: @@ -90,10 +89,9 @@ After the In addition to the actual parsing, the :mod:`weasyprint.css` and from raw tinycss2 tokens into a higher-level form. * Shorthand properties are expanded. For example, ``margin`` becomes ``margin-top``, ``margin-right``, ``margin-bottom`` and ``margin-left``. -* Hyphens in property names are replaced by underscores (``margin-top`` - becomes ``margin_top``) so that they can be used as Python attribute names - later on. This transformation is safe since none for the know (not ignored) - properties have an underscore character. +* Hyphens in property names are replaced by underscores (``margin-top`` becomes + ``margin_top``). This transformation is safe since none for the know (not + ignored) properties have an underscore character. * Selectors are pre-compiled with cssselect2_. .. _tinycss2: https://pypi.python.org/pypi/tinycss2 @@ -124,11 +122,10 @@ an absolute length or a percentage. The final result of the :func:`~weasyprint.css.get_all_computed_styles` function is a big dict where keys are ``(element, pseudo_element_type)`` -tuples, and keys are style dict objects. Elements are -ElementTree elements, while the type of pseudo-element is a string -for eg. ``::first-line`` selectors, or :obj:`None` for “normal” -elements. Style dict objects are dicts with attribute read-only access -mapping property names to the computed values. (The return value is not the +tuples, and keys are style dict objects. Elements are ElementTree elements, +while the type of pseudo-element is a string for eg. ``::first-line`` +selectors, or :obj:`None` for “normal” elements. Style dict objects are dicts +mapping property names to the computed values. (The return value is not the dict itself, but a convenience :func:`style_for` function for accessing it.) @@ -152,13 +149,14 @@ see the module and class docstrings. The :mod:`weasyprint.formatting_structure.build` module takes an ElementTree tree with associated computed styles, and builds a formatting structure. It generates the right boxes for each element and ensures they conform to the -models rules. (Eg. an inline box can not contain a block.) Each box has a +models rules (eg. an inline box can not contain a block). Each box has a :attr:`.style` attribute containing the style dict of computed values. The main logic is based on the ``display`` property, but it can be overridden for some elements by adding a handler in the ``weasyprint.html`` module. This is how ```` and ```` are currently implemented, for example. + This module is rather short as most of HTML is defined in CSS rather than in Python, in the `user agent stylesheet`_. @@ -232,6 +230,6 @@ The code lives in the :mod:`weasyprint.draw` module. Metadata ........ -Finally (step 7), the :mod:`weasyprint.pdf` module parses the PDF file -produced by cairo and makes appends to it to add meta-data: -internal and external hyperlinks, as well as outlines / bookmarks. +Finally (step 7), the :mod:`weasyprint.pdf` module parses (if needed) the PDF +file produced by cairo and adds metadata that cannot be added by cairo: +attachments, embedded files, trim box and bleed box.