Moar docs

.gitignore

@@ -9,3 +9,4 @@
 /.tox
 /MANIFEST
 /docs/_build
+/env

CHANGES

@@ -0,0 +1,11 @@
+tinycss changelog
+=================
+
+
+Version 0.1
+-----------
+
+Relase date to be decided.
+
+First release. Parser support for CSS 2.1, Seloctors 3, Color 3 and
+Paged Media 3.

MANIFEST.in

@@ -1 +1 @@
-include tinycss/speedups.c
+include README.rst CHANGES tinycss/speedups.c

README.rst

@@ -2,15 +2,21 @@ tinycss: CSS parser for Python
 ==============================
 
 *tinycss* is a complete yet simple CSS parser for Python. It supports the full
-syntax and error handling for CSS 2.1 as well as some CSS 3 modules.
+syntax and error handling for CSS 2.1 as well as some CSS 3 modules:
+
+* Selectors 3 (can also find matching elements in a `lxml <http://lxml.de/>`_
+  document)
+* CSS Color 3
+* CSS Paged Media 3
+
 It is designed to be easy to extend for new CSS modules.
 
 
 Quick facts:
 
 * Free software: BSD licensed
 * Compatible Python 2.6+ and 3.x
-* `Documentation <http://packages.python.org/tinycss/>`_
+* `Latest documentation <http://packages.python.org/tinycss/>`_
 * Source, issues and pull requests `on Github
   <https://github.com/SimonSapin/tinycss/>`_
 * Releases `on PyPI <http://pypi.python.org/pypi/tinycss>`_

docs/_static/custom.css

@@ -1,4 +1,17 @@
+div.body {
+    text-align: left;
+}
 div.document p, div.document ul {
-    margin-top: 1em !important;
-    margin-bottom: 1em !important;
+    margin-top: 0;
+    margin-bottom: 1em;
+}
+div.document ul ul {
+    margin-top: 0;
+    margin-bottom: .5em;
+}
+.field-name {
+    padding-right: .5em;
+}
+table.field-list p, table.field-list ul {
+    margin-bottom: .5em;
 }

docs/changelog.rst

@@ -0,0 +1 @@
+.. include:: ../CHANGES

docs/conf.py

@@ -26,7 +26,8 @@
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'sphinx.ext.viewcode']
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx',
+              'sphinx.ext.viewcode', 'sphinx.ext.doctest']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']

docs/extending.rst

@@ -0,0 +1,5 @@
+Extending the parser
+====================
+
+**TODO:**
+Describe how to write a :class:`CoreParser` subclass to extend the parser.

docs/hacking.rst

@@ -0,0 +1,123 @@
+Hacking tinycss
+===============
+
+.. highlight:: sh
+
+Bugs and feature requests
+-------------------------
+
+Bug reports, feature requests and other issues should got to the
+`tinycss issue tracker`_ on Github. Any suggestion or feedback is welcome.
+Please include in full any error message, trackback or other detail that
+could be helpful.
+
+.. _tinycss issue tracker: https://github.com/SimonSapin/tinycss/issues
+
+
+Installing the development version
+----------------------------------
+
+First, get the latest git version::
+
+    git clone https://github.com/SimonSapin/tinycss.git
+    cd tinycss
+
+Cython_ is required. lxml_ is used by the :mod:`~tinycss.selectors3`, but
+is otherwise optional. pytest_ is used to run the test suite. Installing in
+a virtualenv_ is recommended::
+
+    virtualenv env
+    . env/bin/activate
+    pip install Cython lxml pytest
+
+.. _Cython: http://cython.org/
+.. _lxml: http://lxml.de/
+.. _pytest: http://pytest.org/
+.. _virtualenv: http://www.virtualenv.org/
+
+You can omit lxml in the command above if you don’t intend to work on
+selectors.
+
+Then, install tinycss in-place with pip’s *editable mode*. This will also
+build the accelerators::
+
+    pip install -e .
+
+
+Running the test suite
+----------------------
+
+Once you have everything installed (see above), just run pytest from the
+*tinycss* directory::
+
+    py.test
+
+If you chose not to install lxml, use the ``TINYCSS_SKIP_LXML_TESTS``
+environment variable::
+
+    TINYCSS_SKIP_LXML_TESTS=1 py.test
+
+Similarly, there is a ``TINYCSS_SKIP_SPEEDUPS_TESTS`` environment variable
+if the accelerators are not available for some reason.
+
+If you get test failures on a fresh git clone, something may have gone wrong
+during the installation. Otherwise, you probably found a bug. Please
+`report it <#bugs-and-feature-requests>`_.
+
+
+Test in multiple Python versions with tox
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+tox_ automatically creates virtualenvs for various Python versions and
+runs the test suite there::
+
+    pip install tox
+
+Change to the project’s root directory and just run::
+
+    tox
+
+.. _tox: http://tox.testrun.org/
+
+tinycss pre-configures tox to test in CPython 2.6, 2.7, 3.1 and 3.2 as well as
+PyPy, but you can change that with the ``-e`` parameter. Eg::
+
+    tox -e py27,py32
+
+If you use ``--`` in the arguments passed to tox, further arguments
+are passed to the underlying ``py.test`` command::
+
+    tox -- -x --pdb
+
+
+Building the documentation
+--------------------------
+
+This documentation is made with Sphinx_::
+
+    pip install Sphinx
+
+.. _Sphinx: http://sphinx.pocoo.org/
+
+To build the HTML version of the documentation, change to the project’s root
+directory and run::
+
+    python setup.py build_sphinx
+
+The built HTML files are in ``docs/_build/html``.
+
+
+Making a patch and a pull request
+---------------------------------
+
+If you would like to see something included in tinycss, please fork
+`the repository <https://github.com/SimonSapin/tinycss/>`_ on Github
+and make a pull request. Make sure to include tests for your change.
+
+
+Mailing-list
+------------
+
+tinycss does not have a mailing-list of its own for now, but the
+`WeasyPrint mailing-list <http://weasyprint.org/community/>`_
+is appropriate to discuss it.

docs/index.rst

@@ -1,35 +1,4 @@
-tinycss: CSS parser for Python
-==============================
-
-*tinycss* is a complete yet simple CSS parser for Python. It supports the full
-syntax and error handling for CSS 2.1 as well as some CSS 3 modules.
-It is designed to be easy to extend for new CSS modules.
-
-
-Quick facts:
-
-* Free software: BSD licensed
-* Compatible Python 2.6+ and 3.x
-* Source, issues and pull requests `on Github`_
-* Releases `on PyPI`_
-* Install with ``pip install tinycss``
-
-.. _on Github: https://github.com/SimonSapin/tinycss/
-.. _on PyPI: http://pypi.python.org/pypi/tinycss
-
-
-Supported syntax:
-
-* CSS 2.1
-* Selectors 3 (with matching in *lxml* documents)
-* CSS Color 3
-* CSS Paged Media 3
-
-
-.. Contents:
-
-.. toctree::
-   :maxdepth: 2
+.. include:: ../README.rst
 
 
 Requirements
@@ -39,10 +8,14 @@ tinycss is tested on CPython 2.6, 2.7, 3.1 and 3.2 as well as PyPy 1.8;
 it should work on any implementation of **Python 2.6 or later version
 (including 3.x)** of the language.
 
-`lxml <http://lxml.de/>`_ is required for the :mod:`~tinycss.selectors3`
-module, but not for the base parser or other modules.
+lxml_ is required for the :mod:`~tinycss.selectors3` module, but not for
+the base parser or other modules.
+
+Cython_ is used for optional accelerators but is only required for
+development versions on tinycss.
 
-`Cython <http://cython.org/>`_ is used for optional accelerators.
+.. _Cython: http://cython.org/
+.. _lxml: http://lxml.de/
 
 
 Installation
@@ -57,4 +30,23 @@ Installing with `pip <http://www.pip-installer.org/>`_ should Just Work:
 The release tarballs contain pre-*cythoned* C files for the accelerators:
 you will not need Cython to install like this.
 If the accelerators fail to build for some reason, tinycss will
-print a warning and fall back on a pure-Python installation.
+print a warning and fall back to a pure-Python installation.
+
+
+Documentation
+-------------
+
+.. Have this page in the sidebar, but do not show a link to itself here:
+
+.. toctree::
+    :hidden:
+
+    self
+
+.. toctree::
+    :maxdepth: 2
+
+    parsing
+    extending
+    hacking
+    changelog

docs/parsing.rst

@@ -0,0 +1,104 @@
+Parsing with tinycss
+====================
+
+.. highlight:: python
+
+Quickstart
+----------
+
+Import *tinycss*, make a parser object, and parse a stylesheet:
+
+.. doctest::
+
+    >>> import tinycss
+    >>> parser = tinycss.make_parser()
+    >>> stylesheet = parser.parse_stylesheet_bytes(b'''@import "foo.css";
+    ...     p.error { color: red }''')
+    >>> for rule in stylesheet.rules:
+    ...     print(rule)
+    <ImportRule 1:1 foo.css>
+    <RuleSet at 2:5 p.error>
+
+You’ll get a :class:`~tinycss.core.Stylesheet` object which contains
+all the parsed content.
+
+
+Parsers
+-------
+
+Parsers are subclasses of :class:`tinycss.css21.CSS21Parser`. Various subclasses
+add support for more syntax. You can choose which features to enable
+by making a new parser class with multiple inheritance, but there is also
+a convenience function to do that:
+
+.. module:: tinycss
+
+.. autofunction:: make_parser(*base_classes, with_selectors3=False, with_page3=False, **kwargs)
+
+
+.. module:: tinycss.core
+
+Parsing a stylesheet
+~~~~~~~~~~~~~~~~~~~~
+
+Parser classes have three different methods to parse CSS stylesheet,
+depending on whether you have a file, a byte string, or an Unicode string.
+
+.. automethod:: CoreParser.parse_stylesheet_file
+.. automethod:: CoreParser.parse_stylesheet_bytes
+.. automethod:: CoreParser.parse_stylesheet
+
+
+Parsing a ``style`` attribute
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. automethod:: CoreParser.parse_style_attr
+
+
+Tokens
+------
+
+Some parts of a stylesheet (such as property values) are not parsed
+by tinycss. They appear as tokens instead.
+All of these objects have :obj:`line` and :obj:`column` attributes (not
+repeated every time fore brevity) that indicate where in the CSS source this
+object was read.
+
+tinycss does not know which properties and which values a given User Agent
+wants to support: it is the UA’s responsibility to ignore unknown and
+unsupported values, and fall back on any previous declaration.
+
+.. module:: tinycss.token_data
+
+.. autoclass:: Token()
+.. autoclass:: tinycss.speedups.CToken()
+.. autoclass:: ContainerToken()
+
+    .. method:: __iter__, __len__
+
+        Shortcuts for accessing :attr:`content`.
+
+.. autoclass:: FunctionToken()
+
+
+Parsed objects
+--------------
+
+These data structures make up the results of the various parsing methods.
+All of these objects have :obj:`line` and :obj:`column` attributes (not
+repeated every time fore brevity) that indicate where in the CSS source this
+object was read.
+
+.. currentmodule:: tinycss.core
+
+.. autoclass:: Stylesheet()
+.. autoclass:: ParseError()
+.. autoclass:: RuleSet()
+.. autoclass:: Declaration()
+
+.. module:: tinycss.css21
+
+.. autoclass:: PropertyDeclaration()
+.. autoclass:: PageRule()
+.. autoclass:: MediaRule()
+.. autoclass:: ImportRule()