Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Docs: Update the Hacking page.

  • Loading branch information...
commit 3fb940ad49b3b0e092d585729cbd70c7e7ad3f61 1 parent ba987f0
@SimonSapin SimonSapin authored
Showing with 94 additions and 78 deletions.
  1. +92 −76 docs/hacking.rst
  2. +2 −2 docs/tutorial.rst
View
168 docs/hacking.rst
@@ -38,7 +38,7 @@ Much like `in web browsers
<http://www.html5rocks.com/en/tutorials/internals/howbrowserswork/#The_main_flow>`_,
the rendering of a document in WeasyPrint goes like this:
-1. The HTML document is fetched and parsed into a DOM tree
+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
@@ -48,110 +48,120 @@ the rendering of a document in WeasyPrint goes like this:
7. The pages are drawn in a PDF file through a cairo surface.
8. Cairo’s PDF is modified to add metadata such as bookmarks and hyperlinks.
-Documents
-.........
-
-WeasyPrint’s “entry point” is the ``Document`` class. An instance handles
-a document for all of its lifetime. It is responsible of calling other parts
-of the code for each step listed above.
-
-The document is lazy: the various steps of the rendering are only done
-when required (ie. when relevant attributes are accessed.)
HTML
....
-Not much to see here. lxml.html_ handles step 1 and gives a *DOM tree*.
-The lxml API is not actually DOM, but we’ll call it that anyway. The lxml
-object for the root element (usually ``<html>``) is stored as the ``dom``
-attribute of the document.
+Not much to see here. The :class:`weasyprint.HTML` class is a thin wrapper
+around lxml.html_ which handles step 1 and gives a tree of HTML *elements*.
+Although the actual API is different, this tree is conceptually the same
+as what web browsers call *the DOM*.
.. _lxml.html: http://lxml.de/lxmlhtml.html
+
CSS
...
-Steps 2 and 3 happen in the ``weasyprint.css`` package. CSS stylesheets are
-parsed with cssutils_. ``@import`` and ``@media`` rules are resolved to find
-applicable rule sets. Then the ``weasyprint.css.validation`` module filters out
-declarations with properties unknown to or unsupported by WeasyPrint or with
-illegal or unsupported values.
-
-
-.. _cssutils: http://cthedot.de/cssutils/
-.. _lxml.cssselect: http://lxml.de/cssselect.html
+As with HTML, CSS stylesheets are parsed in the :class:`weasyprint.CSS` class
+with an external library, tinycss_.
+After the In addition to the actual parsing, the :mod:`weasyprint.css` and
+:mod:`weasyprint.css.validation` modules do some pre-processing:
-As well as validation, several transformations are made at or around
-this point:
-
-* Shorthand properties are expanded. For example, ``margin`` is replaced by
+* Unknown and unsupported declarations are ignored with warnings.
+ Remaining property values are parsed in a property-specific way
+ from raw tinycss tokens into a higher-level form.
+* Shorthand properties are expanded. For example, ``margin`` becomes
``margin-top``, ``margin-right``, ``margin-bottom`` and ``margin-left``.
-* Some values are simplified. They come as a list as a list of cssutils
- `Value objects`_. For example, keyword values are replaced by simple
- strings and the list is dropped when its length is always one for a given
- property.
* 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.
+ later on. This transformation is safe since none for the know (not ignored)
+ properties have an underscore character.
+* Selectors are pre-compiled with cssselect_.
+
+.. _tinycss: http://packages.python.org/tinycss/
+.. _cssselect: http://packages.python.org/cssselect/
-.. _Value objects: http://packages.python.org/cssutils/docs/css.html#values
-After that, the cascade_ (that’s the C in CSS!), together with inhertance
-and initial values, assigns a value for each property to each DOM element.
-These values are *computed* in ``weasyprint.css.computed_values``: lengths
-are converted to pixels, etc. The objects representing the values are
-simplified further: pixel length are simple floating points numbers.
-Some values however are still cssutils objects to avoid ambiguities (eg.
-percentages.)
+The cascade
+...........
+
+After that and still in the :mod:`weasyprint.css` package, the cascade_
+(that’s the C in CSS!) applies the stylesheets to the element tree.
+Selectors associate property declarations to elements. In case of conflicting
+declarations (different values for the same property on the same element),
+the one with the highest *weight* wins. Weights are based on the stylesheet’s
+:ref:`origin <stylesheet-origins>`, ``!important`` markers, selector
+specificity and source order. Missing values are filled in through
+*inheritance* (from the parent element) or the property’s *initial value*,
+so that every element has a *specified value* for every property.
.. _cascade: http://www.w3.org/TR/CSS21/cascade.html
-Finally, the computed style for all DOM elements is stored in the
-``computed_styles`` attribute of the document object.
+These *specified values* are turned into *computed values* in the
+``weasyprint.css.computed_values`` module. Keywords and lengths in various
+units are converted to pixels, etc. At this point the value for some
+properties can be represented by a single number or string, but some require
+more complex objects. For example, a :class:`Dimension` object can be either
+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 :obj:``StyleDict`` objects. Elements are lxml objects,
+while the type of pseudo-element is a string for eg. ``::first-line``
+selectors, or :obj:`None` for “normal” elements. :obj:`StyleDict` objects
+are dicts with attribute access 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.)
+
Formatting structure
....................
-The `visual formatting model`_ explains how *elements* (from the DOM tree)
+The `visual formatting model`_ explains how *elements* (from the lxml tree)
generate *boxes* (in the formatting structure). This is step 4 above.
Boxes may have children and thus form a tree, much like elements. This tree
-is generally close but not identical to the DOM tree: some elements generate
-no or more than one box.
+is generally close but not identical to the lxml tree: some elements generate
+more than one box or none.
.. _visual formatting model: http://www.w3.org/TR/CSS21/visuren.html
Boxes are of a lot of different kinds. For example you should not confuse
*block-level boxes* and *block containers*, though *block boxes* are both.
-The ``weasyprint.formatting_structure.boxes`` module has a whole hierarchy of
-classes to represent all these boxes. We won’t go into the details here, see
-the module and class docstrings.
+The :mod:`weasyprint.formatting_structure.boxes` module has a whole hierarchy
+of classes to represent all these boxes. We won’t go into the details here,
+see the module and class docstrings.
-The ``weasyprint.formatting_structure.build`` module takes a DOM tree with
+The :mod:`weasyprint.formatting_structure.build` module takes an lxml 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 ``some_box.style``
-attribute containing computed values for each known CSS property.
+(Eg. an inline box can not contain a block.) Each box has a :attr:`.style`
+attribute containing the :class:`StyleDict` 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.
+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 ``<img>`` and ``<td colspan=3>`` 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`_.
-The box for the root element (and, through its ``children`` attribute, the
-whole tree) is set to the ``formatting_structure`` attribute of the document.
+The :func:`~weasyprint.formatting_structure.build.build_formatting_structure`
+function returns the box for the root element (and, through its
+:attr:`children` attribute, the whole tree).
.. _user agent stylesheet: https://github.com/Kozea/WeasyPrint/blob/master/weasyprint/css/html5_ua.css
+
Layout
......
Step 5 is the layout. You could say the everything else is glue code and
this is where the magic happens.
-During the layout the document’s content is … laid out on pages. This is when
-we decide where to do line breaks and page breaks. If a break happens inside
-of a box, that box is split into two (or more) boxes in the layout result.
+During the layout the document’s content is, well, laid out on pages.
+This is when we decide where to do line breaks and page breaks. If a break
+happens inside of a box, that box is split into two (or more) boxes in the
+layout result.
According to the `box model`_, each box has rectangular margin, border,
padding and content areas:
@@ -161,33 +171,39 @@ padding and content areas:
.. image:: _static/box_model.png
:align: center
-While ``box.style`` contains computed values, the `used values`_ are set
-as attributes of the ``Box`` object itself during the layout. This
+While :obj:`box.style` contains computed values, the `used values`_ are set
+as attributes of the :class:`Box` object itself during the layout. This
include resolving percentages and especially ``auto`` values into absolute,
pixel lengths. Once the layout done, each box has used values for
-margins, border width, padding of each four sides, as well as the ``width``
-and ``height`` of the content area. They also have ``position_x`` and
-``position_y``, the absolute coordinates of the top-left corner of the
-margin box (**not** the content box) from the top-left corner of the page.
+margins, border width, padding of each four sides, as well as the
+:attr:`width` and :attr:`height` of the content area. They also have
+:attr:`position_x`` and :attr:`position_y``, the absolute coordinates of the
+top-left corner of the margin box (**not** the content box) from the top-left
+corner of the page.\ [#]_
+
+Boxes also have helpers methods such as :meth:`content_box_y` and
+:meth:`margin_width` that give other metrics that can be useful in various
+parts of the code.
-.. _used values: http://www.w3.org/TR/CSS21/cascade.html#used-value
+The final result of the layout is a list of :class:`PageBox` objects.
-Boxes also have helpers methods such as ``content_box_y()`` and
-``margin_width()`` that give other metrics that can be useful in various
-parts of the code.
+.. [#] These are the coordinates *if* no `CSS transform`_ applies.
+ Transforms change the actual location of boxes, but they are applies
+ later during drawing and do not affect layout.
+.. _used values: http://www.w3.org/TR/CSS21/cascade.html#used-value
+.. _CSS transform: http://www.w3.org/TR/css3-transforms/
-When the layout is done, a list of ``PageBox`` objects is set to the
-``pages`` attribute of the document.
Stacking
........
-In step 6, the boxes are reorder by the ``weasyprint.stacking`` module
+In step 6, the boxes are reorder by the :mod:`weasyprint.stacking` module
to observe `stacking rules`_ such as the ``z-index`` property.
-The result is a tree of `stacking contexts`.
+The result is a tree of *stacking contexts*.
.. _stacking rules: http://www.w3.org/TR/CSS21/zindex.html
+
Drawing
.......
@@ -196,14 +212,14 @@ Since each box has absolute coordinates on the page from the layout step,
the logic here should be minimal. If you find yourself adding a lot of logic
here, maybe it should go in the layout or stacking instead.
-The code lives in the ``weasyprint.draw`` module and is called by the
-``write_to`` method of the document.
+The code lives in the :mod:`weasyprint.draw` module.
.. _cairo: http://cairographics.org/pycairo/
+
Metadata
........
-Finally (step 8), the ``weasyprint.pdf`` parses the PDF file produced by cairo
-and makes an *incremental update* to add internal and external hyperlinks,
-as well as outlines / bookmarks.
+Finally (step 8), 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.
View
4 docs/tutorial.rst
@@ -74,14 +74,14 @@ you can also pass that, although the argument must be named:
.. code-block:: python
- # The argument must be named: HTML('<h1>foo') is a filename
+ # HTML('<h1>foo') would be filename
HTML(string='''
<h1>The title</h1>
<p>Content goes here
''')
CSS(string='@page { size: A3; margin: 1cm }')
- # The argument must be named
+ # Use a different lxml parser:
HTML(tree=lxml.html.html5parser.parse('../foo.html'))
Please sign in to comment.
Something went wrong with that request. Please try again.