Permalink
Browse files

Moar docs

  • Loading branch information...
1 parent 42a52f8 commit 7cb11df26a3e8f26bad23f13eeb74ecb1a1001a7 @SimonSapin SimonSapin committed Mar 28, 2012
Showing with 453 additions and 111 deletions.
  1. +1 −0 .gitignore
  2. +11 −0 CHANGES
  3. +1 −1 MANIFEST.in
  4. +8 −2 README.rst
  5. +15 −2 docs/_static/custom.css
  6. +1 −0 docs/changelog.rst
  7. +2 −1 docs/conf.py
  8. +5 −0 docs/extending.rst
  9. +123 −0 docs/hacking.rst
  10. +28 −36 docs/index.rst
  11. +104 −0 docs/parsing.rst
  12. +2 −2 tinycss/__init__.py
  13. +43 −40 tinycss/core.py
  14. +29 −18 tinycss/css21.py
  15. +5 −2 tinycss/speedups.pyx
  16. +75 −7 tinycss/token_data.py
View
@@ -9,3 +9,4 @@
/.tox
/MANIFEST
/docs/_build
+/env
View
11 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.
View
@@ -1 +1 @@
-include tinycss/speedups.c
+include README.rst CHANGES tinycss/speedups.c
View
@@ -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>`_
View
@@ -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;
}
View
@@ -0,0 +1 @@
+.. include:: ../CHANGES
View
@@ -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']
View
@@ -0,0 +1,5 @@
+Extending the parser
+====================
+
+**TODO:**
+Describe how to write a :class:`CoreParser` subclass to extend the parser.
View
@@ -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.
View
@@ -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
View
@@ -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()
Oops, something went wrong.

0 comments on commit 7cb11df

Please sign in to comment.