Add documentation for color modules

Author: liZe

docs/api_reference.rst

@@ -38,31 +38,49 @@ serialization-related functions are available:
 .. autofunction:: serialize_identifier
 
 
+Color Level 3
+-------------
+
 .. module:: tinycss2.color3
+.. autofunction:: parse_color
+.. autoclass:: RGBA
 
 
-Color
------
+Color Level 4
+-------------
 
+.. module:: tinycss2.color4
 .. autofunction:: parse_color
-.. autoclass:: RGBA
+.. autoclass:: Color
+   :members:
+.. autodata:: COLOR_SPACES
+.. autodata:: D50
+.. autodata:: D65
 
+Color Level 5
+-------------
 
-.. module:: tinycss2.nth
+.. module:: tinycss2.color5
+.. autofunction:: parse_color
+.. autoclass:: Color
+   :show-inheritance:
+.. autodata:: COLOR_SPACES
+.. autodata:: D50
+.. autodata:: D65
 
 
 <An+B>
 ------
 
+.. module:: tinycss2.nth
 .. autofunction:: parse_nth
 
 
-.. module:: tinycss2.ast
-
-
 AST nodes
 ---------
 
+.. module:: tinycss2.ast
+
 Various parsing functions return a **node** or a list of nodes. Some types of
 nodes contain nested nodes which may in turn contain more nodes, forming
 together an **abstract syntax tree**.

tinycss2/color4.py

@@ -4,13 +4,16 @@
 from .color3 import _BASIC_COLOR_KEYWORDS, _EXTENDED_COLOR_KEYWORDS, _HASH_REGEXPS
 from .parser import parse_one_component_value
 
+#: XYZ values of the D50 white point, normalized to Y=1.
 D50 = (0.3457 / 0.3585, 1, (1 - 0.3457 - 0.3585) / 0.3585)
+#: XYZ values of the D65 white point, normalized to Y=1.
 D65 = (0.3127 / 0.3290, 1, (1 - 0.3127 - 0.3290) / 0.3290)
 _FUNCTION_SPACES = {
     'srgb', 'srgb-linear',
     'display-p3', 'a98-rgb', 'prophoto-rgb', 'rec2020',
     'xyz', 'xyz-d50', 'xyz-d65'
 }
+#: Supported color spaces.
 COLOR_SPACES = _FUNCTION_SPACES | {'hsl', 'hwb', 'lab', 'lch', 'oklab', 'oklch'}
 
 

tinycss2/color5.py

@@ -1,8 +1,12 @@
 from . import color4
 
+#: Supported color spaces.
 COLOR_SPACES = color4.COLOR_SPACES | {'device-cmyk'}
+#: Supported color schemes.
 COLOR_SCHEMES = {'light', 'dark'}
+#: XYZ values of the D50 white point, normalized to Y=1.
 D50 = color4.D50
+#: XYZ values of the D65 white point, normalized to Y=1.
 D65 = color4.D65
 
 
@@ -11,6 +15,22 @@ class Color(color4.Color):
 
 
 def parse_color(input, color_schemes=None):
+    """Parse a color value as defined in CSS Color Level 5.
+
+    https://www.w3.org/TR/css-color-5/
+
+    :type input: :obj:`str` or :term:`iterable`
+    :param input: A string or an iterable of :term:`component values`.
+    :type color_schemes: :obj:`str` or :term:`iterable`
+    :param color_schemes: the ``'normal'`` string, or an iterable of color
+        schemes used to resolve the ``light-dark()`` function.
+    :returns:
+        * :obj:`None` if the input is not a valid color value.
+          (No exception is raised.)
+        * The string ``'currentcolor'`` for the ``currentcolor`` keyword
+        * A :class:`Color` object for every other values, including keywords.
+
+    """
     color = color4.parse_color(input)
 
     if color: