diff --git a/pages/using.rst b/pages/using.rst index bdeab8d3..5067d7ac 100644 --- a/pages/using.rst +++ b/pages/using.rst @@ -54,10 +54,85 @@ any other Python library: import weasyprint weasyprint.HTML('http://weasyprint.org/').write_pdf('/tmp/weasyprint-website.pdf') -**TODO**: full documentation for the public API. +The public API for WeasyPrint 0.6 is made of two classes: ``HTML`` and ``CSS`` + + +API stability +............. + +Everything described here is considered “public”: this is what you can rely +on. We will try to maintain backward-compatibility, although there is no +hard promise until version 1.0. + +Anything else should not be used outside of WeasyPrint itself: we reserve +the right to change it or remove it at any point. Please do `tell us`_ +if you feel like something should be in the public API. It can probably +be added in the next version. + +.. _tell us: /community/ + + +The ``weasyprint.CSS`` class +............................ + +A ``CSS`` object represents a CSS stylesheet parsed by cssutils. + +You can just create an instance with a positional argument and it will try +to guess if the input is a filename, an absolute URL, or a file-like object: +``stylesheet = CSS(something)`` + +Alternatively, you can name the argument so that no guessing is +involved: + +* ``CSS(filename=foo)`` a filename, absolute or relative to + the current directory. +* ``CSS(url=foo)`` an absolute, fully qualified URL. +* ``CSS(file_obj=foo)`` a file-like object: any object with + a ``read()`` method. +* ``CSS(string=foo)`` a string of HTML source. + (This argument must be named.) + +Specifying multiple inputs is an error: ``CSS(filename=foo, url=bar)`` + +Optional, additional named arguments: + +* ``encoding``: force the character encoding +* ``base_url``: used to resolve relative URLs (eg. in ``@import``) + If not passed explicitly, try to use the input filename, URL, or + ``name`` attribute of file objects. + +``CSS`` objects have no public attribute or method. They are only meant to +be used in the ``write_pdf`` or ``write_png`` method. (See below.) + + +The ``weasyprint.HTML`` class +............................. + +An ``HTML`` object represents an HTML document parsed by lxml. +An instance is created in exactly the same way as ``CSS``. + +It has two public methods: + +``HTML.write_pdf(target=None, stylesheets=None)`` + Render the document with stylesheets from three *origins*: + + * The HTML5 `user agent stylesheet`_; + * Author stylesheets embedded in the document in ``