Document color and <An+B> parsing.

Author: SimonSapin

docs/index.rst

@@ -45,6 +45,23 @@ some serialization-related functions are available:
 .. autofunction:: serialize_identifier
 
 
+.. module:: tinycss2.color3
+
+Color
+=====
+
+.. autofunction:: parse_color
+.. autoclass:: RGBA
+
+
+.. module:: tinycss2.nth
+
+<An+B>
+======
+
+.. autofunction:: parse_nth
+
+
 .. module:: tinycss2.ast
 
 AST nodes

tinycss2/color3.py

@@ -9,29 +9,42 @@
 class RGBA(collections.namedtuple('RGBA', ['red', 'green', 'blue', 'alpha'])):
     """An RGBA color.
 
-    A tuple of four floats in the 0..1 range: ``(r, g, b, a)``.
-    Also has :attr:`red`, :attr:`green`, :attr:`blue` and :attr:`alpha`
-    attributes to access the same values.
+    A tuple of four floats in the 0..1 range: ``(red, green, blue, alpha)``.
+
+    .. attribute:: red
+
+        Convenience access to the red channel. Same as ``rgba[0]``.
+
+    .. attribute:: green
+
+        Convenience access to the green channel. Same as ``rgba[1]``.
+
+    .. attribute:: blue
+
+        Convenience access to the blue channel. Same as ``rgba[2]``.
+
+    .. attribute:: alpha
+
+        Convenience access to the alpha channel. Same as ``rgba[3]``.
 
     """
-    type = 'rgba'
 
 
 def parse_color(input):
     """Parse a color value as defined in `CSS Color Level 3
     <http://www.w3.org/TR/css3-color/>`_.
 
-    :param token:
+    :param input:
         A :term:`string`, or a single :term:`component value`.
     :returns:
-        * :obj:`None` if the token is not a valid CSS 3 color value.
+        * :obj:`None` if the input is not a valid color value.
           (No exception is raised.)
         * The string ``'currentColor'`` for the *currentColor* keyword
         * Or a :class:`RGBA` object for every other values
           (including keywords, HSL and HSLA.)
-          The alpha channel is clipped to [0, 1], but R, G, or B can be
-          out of range (eg. ``rgb(-51, 306, 0)`` is represented as
-          ``(-.2, 1.2, 0, 1)``.)
+          The alpha channel is clipped to [0, 1]
+          but red, green, or blue can be out of range
+          (eg. ``rgb(-10%, 120%, 0%)`` is represented as ``(-0.1, 1.2, 0, 1)``.)
 
     """
     if isinstance(input, basestring):

tinycss2/nth.py

@@ -3,11 +3,19 @@
 
 
 def parse_nth(input):
-    """Parse <An+B>, as found in ``:nth-child()`` and related pseudo-classes.
+    """Parse `<An+B> <http://dev.w3.org/csswg/css-syntax-3/#anb>`_,
+    as found in `:nth-child()
+    <http://dev.w3.org/csswg/selectors/#nth-child-pseudo>`_
+    and related Selector pseudo-classes.
+
+    Although tinycss2 does not include a full Selector parser,
+    this bit of syntax is included as it is particularly tricky to define
+    on top of a CSS tokenizer.
 
     :param input:
         A :term:`string`, or an iterable yielding :term:`component values`
-        (eg. the arguments of a functional pseudo-class.)
+        (eg. the :attr:`~tinycss2.ast.FunctionBlock.arguments`
+        of a functional pseudo-class.)
     :returns:
         A ``(a, b)`` tuple of integers, or :obj:`None` if the input is invalid.