Clean up some documentation.

README.rst

@@ -4,7 +4,8 @@
    :alt: CI status image
    :target: https://github.com/ubernostrum/webcolors/actions?query=workflow%3ACI
 
-``webcolors`` is a module for working with HTML/CSS color definitions.
+``webcolors`` is a module for working with and converting between the
+various HTML/CSS color formats.
 
 Support is included for normalizing and converting between the
 following formats (RGB colorspace only; conversion to/from HSL can be
@@ -30,7 +31,7 @@ For example:
 
 Implementations are also provided for the HTML5 color parsing and
 serialization algorithms. For example, parsing the infamous
-"chucknorris" string into an rgb() triplet:
+"chucknorris" string into an ``rgb()`` triplet:
 
 .. code-block:: python
 

docs/contents.rst

@@ -3,8 +3,8 @@
 .. _contents:
 
 
-Module contents
-===============
+API reference
+=============
 
 The contents of the ``webcolors`` module fall into five categories:
 

docs/index.rst

@@ -1,9 +1,8 @@
 webcolors |release|
 ===================
 
-This module provides utility functions for working with the color names and
-color value formats defined by the HTML and CSS specifications for use in
-documents on the web.
+``webcolors`` is a module for working with and converting between the various
+HTML/CSS color formats.
 
 Support is included for normalizing and converting between the following
 formats (RGB colorspace only; conversion to/from HSL can be handled by the
@@ -19,15 +18,19 @@ formats (RGB colorspace only; conversion to/from HSL can be handled by the
 
 * Percentage ``rgb()`` triplet
 
-For example::
+For example:
+
+.. code-block:: python
 
     >>> import webcolors
     >>> webcolors.hex_to_name("#daa520")
     'goldenrod'
 
 Implementations are also provided for the HTML5 color parsing and serialization
 algorithms. For example, parsing the infamous "chucknorris" string into an
-``rgb()`` triplet::
+``rgb()`` triplet:
+
+.. code-block:: python
 
     >>> import webcolors
     >>> webcolors.html5_parse_legacy_color("chucknorris")
@@ -38,13 +41,24 @@ Documentation contents
 ----------------------
 
 .. toctree::
+   :caption: Getting started
    :maxdepth: 1
 
    install
+
+.. toctree::
+   :caption: Reference
+   :maxdepth: 1
+
    colors
    conventions
    contents
    conformance
+
+.. toctree::
+   :caption: Other documentation
+   :maxdepth: 1
+
    changelog
    faq
 
@@ -55,4 +69,4 @@ Documentation contents
   * `CSS1: Color units <http://www.w3.org/TR/CSS1/#color-units>`_
   * `CSS2: Colors <http://www.w3.org/TR/CSS2/syndata.html#color-units>`_
   * `CSS3 color module <http://www.w3.org/TR/css3-color/>`_
-  * `HTML5: Colors <http://www.w3.org/TR/html5/infrastructure.html#colors>`_
+  * `HTML5: Colors <https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#colours>`_