Document the public API.

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 ``<style>`` elements or
+      linked by ``<link rel=stylesheet>`` elements;
+    * User stylesheets provided in the ``stylesheets`` parameter to this
+      method. If provided, ``stylesheets`` must be an iterable where elements
+      are ``CSS`` instances or anything that can be passed to ``CSS()``.
+
+    ``target`` can be a filename or a file-like object (anything with a
+    ``write()`` method) where the PDF output is written.
+    If ``target`` is not provided, the method returns PDF as a byte string.
+
+``HTML.write_png(target=None, stylesheets=None)``
+    Like ``write_pdf``, but writes PNG instead of PDF.
+
+
+.. _user agent stylesheet: https://github.com/Kozea/WeasyPrint/blob/master/weasyprint/css/html5_ua.css
 
-If you want to change something in WeasyPrint or just see how it works,
-it’s time to `start hacking </hacking>`_!
 
 Errors
 ------
@@ -68,6 +143,7 @@ probably not a bug in WeasyPrint, though.)
 
 .. _issue tracker: http://redmine.kozea.fr/projects/weasyprint/issues
 
+
 Logging
 -------
 
@@ -90,3 +166,10 @@ Logged messaged will go to stderr by default.
 See the `logging documentation`_ if you want to change that.
 
 .. _logging documentation: http://docs.python.org/library/logging.html
+
+
+What’s next
+-----------
+
+If you want to change something in WeasyPrint or just see how it works,
+it’s time to `start hacking </hacking>`_!