Additional documentation cleanup.

Author: ubernostrum

docs/changelog.rst

@@ -139,9 +139,9 @@ Version 1.9.1
 
 Released June 2019
 
-* The ``__version__`` attribute of the installed webcolors module, although not
-  documented or referenced anywhere, was accidentally not updated in the 1.9
-  release. It has now been updated (and now indicates 1.9.1).
+* The ``__version__`` attribute of the installed ``webcolors`` module, although
+  not documented or referenced anywhere, was accidentally not updated in the
+  1.9 release. It has now been updated (and now indicates 1.9.1).
 
 
 Version 1.9
@@ -154,7 +154,7 @@ Released June 2019
 
 * When asked to provide a color name, using the CSS3/SVG set of names, for the
   hexadecimal value ``#808080``, the integer triplet ``rgb(128, 128, 128)``, or
-  the percentage triplet ``rgb(50%, 50%, 50%)``, webcolors now always returns
+  the percentage triplet ``rgb(50%, 50%, 50%)``, ``webcolors`` now always returns
   ``u'gray'``, never ``u'grey'``. Previously, the behavior could be
   inconsistent as it depended on the Python version in use; ``u'gray'`` was
   picked because it was the spelling variant used in HTML 4, CSS1, and CSS2.
@@ -215,7 +215,7 @@ Version 1.5
 
 Released March 2015
 
-* Python 3 support: webcolors now supports Python 3.3.
+* Python 3 support: ``webcolors`` now supports Python 3.3.
 
 * Added :ref:`HTML5 color algorithms <html5-algorithms>`.
 

docs/colors.rst

@@ -149,8 +149,8 @@ of `the HTML5 specification's section on colors`_.
 What this module supports
 -------------------------
 
-The webcolors module supports the following methods of specifying sRGB colors,
-and conversions between them:
+The ``webcolors`` module supports the following methods of specifying sRGB
+colors, and conversions between them:
 
 * Six-digit hexadecimal
 
@@ -162,7 +162,7 @@ and conversions between them:
 
 * The defined named colors of HTML 4, CSS2, CSS2.1, and CSS3
 
-The webcolors module **does not support**:
+The ``webcolors`` module **does not support**:
 
 * The CSS1 named colors, which did not have defined values
 

docs/conformance.rst

@@ -4,12 +4,13 @@
 Conformance and testing
 =======================
 
-Much of the behavior of webcolors is dictated by the relevant web standards,
-which define the acceptable color formats, how to determine valid values for
-each format and the values corresponding to defined color names. Maintaining
-correct conversions and conformance to those standards is crucial.
+Much of the behavior of ``webcolors`` is dictated by the relevant web
+standards, which define the acceptable color formats, how to determine valid
+values for each format and the values corresponding to defined color
+names. Maintaining correct conversions and conformance to those standards is
+crucial.
 
-The source distribution of webcolors (the ``.tar.gz`` file you can download
+The source distribution of ``webcolors`` (the ``.tar.gz`` file you can download
 from the Python Package Index) includes a ``tests/`` directory containing a
 normal test suite as well as supplemental test files which perform more
 comprehensive verification.
@@ -18,8 +19,8 @@ comprehensive verification.
 The normal test suite
 ---------------------
 
-The normal test suite for webcolors aims for 100% coverage of code paths, but
-does *not* aim for 100% coverage of possible color value inputs and
+The normal test suite for ``webcolors`` aims for 100% coverage of code paths,
+but does *not* aim for 100% coverage of possible color value inputs and
 outputs. Instead, it uses a small number of test values to routinely exercise
 various functions.
 
@@ -51,9 +52,9 @@ the results of test runs online `at GitHub
 <https://github.com/ubernostrum/webcolors/actions/workflows/ci.yml/>`_.
 
 However, the normal test suite cannot guarantee that the color definitions
-included in webcolors correspond to those in the relevant standards, and cannot
-provide guarantees of correct conversions for all possible values. For that,
-additional tests are required.
+included in ``webcolors`` correspond to those in the relevant standards, and
+cannot provide guarantees of correct conversions for all possible values. For
+that, additional tests are required.
 
 
 .. _full-verification:
@@ -64,16 +65,16 @@ Full verification tests
 These tests are contained in two files which are not executed during normal
 test runs: ``tests/definitions.py`` and ``tests/full_colors.py``. They are not
 run as part of the normal test suite, but are run prior to each release of
-webcolors.
+``webcolors``.
 
 
 Verifying color definitions
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The ``definitions.py`` test file verifies that the color definitions in
-webcolors are correct. It does this by downloading the relevant standards
+``webcolors`` are correct. It does this by downloading the relevant standards
 documents as HTML, parsing out the color definitions in them, and comparing
-them to the definitions in webcolors. That consists of:
+them to the definitions in ``webcolors``. That consists of:
 
 * Parsing out the names and hexadecimal values of the 16 named colors in the
   HTML 4 standard, and checking that the names and values in
@@ -102,7 +103,7 @@ For conversions between hexadecimal and integer ``rgb()``, it generates all
 16,777,216 possible color values for each format in order (starting at
 ``#000000`` and ``(0,0,0)`` and incrementing), and verifies that each one
 converts to the corresponding value in the other format. Thus, it is possible
-to be confident that webcolors provides correct conversions between all
+to be confident that ``webcolors`` provides correct conversions between all
 possible color values in those formats.
 
 Testing the correctness of conversion to and from percentage ``rgb()``,
@@ -124,7 +125,7 @@ however, is more difficult, and a full test is not provided, for two reasons:
    uncountably infinite, testing all legal values is not possible on current
    hardware in any reasonable amount of time.
 
-Since precise correctness and completeness are not achievable, webcolors
+Since precise correctness and completeness are not achievable, ``webcolors``
 instead aims to achieve *consistency* in conversions. Specifically, the
 ``full_colors.py`` test generates all 16,777,216 integer ``rgb()`` triplets,
 and for each such triplet `t` verifies that the following assertion holds:
@@ -137,11 +138,11 @@ and for each such triplet `t` verifies that the following assertion holds:
 Running the tests
 -----------------
 
-The standard test runner for webcolors is `nox <https://nox.thea.codes/>`_,
+The standard test runner for ``webcolors`` is `nox <https://nox.thea.codes/>`_,
 which supports testing against multiple Python versions and executing a variety
-of different test tasks. The source distribution of webcolors includes its
+of different test tasks. The source distribution of ``webcolors`` includes its
 ``noxfile.py`` file. To run the tests, install nox (``pip install nox``), then
-download and unpack a git checkout or source package of webcolors.
+download and unpack a git checkout or source package of ``webcolors``.
 
 To run the normal test suite against the complete set of supported Python
 versions:
@@ -160,8 +161,8 @@ versions:
       py -m pip install nox
       py -m nox
 
-This requires that you have each supported version of Python (for webcolors
-|release|, this is 3.7, 3.8, 3.9, 3.10, and 3.11) available. To test only
+This requires that you have each supported version of Python (for ``webcolors``
+|release|, this is 3.8, 3.9, 3.10, 3.11, and 3.12) available. To test only
 against a specific version of Python, use the ``--python`` flag and pass the
 version to test. For example, to test on Python 3.10:
 
@@ -178,8 +179,8 @@ version to test. For example, to test on Python 3.10:
       py -m nox --python "3.10"
 
 To run the full verification tests for definition correctness and conversions,
-specify the "release" test keyword instead (so named because these tests
-are usually run only prior to a new release of webcolors):
+specify the "release" test keyword instead (so named because these tests are
+usually run only prior to a new release of ``webcolors``):
 
 .. tab:: macOS/Linux/other Unix
 

docs/contents.rst

@@ -6,7 +6,7 @@
 Module contents
 ===============
 
-The contents of the webcolors module fall into five categories:
+The contents of the ``webcolors`` module fall into five categories:
 
 1. A set of (optional) data types for representing color values.
 
@@ -21,7 +21,7 @@ The contents of the webcolors module fall into five categories:
 
 See :ref:`the documentation regarding conventions <conventions>` for
 information regarding the types and representation of various color formats in
-webcolors.
+``webcolors``.
 
 All conversion functions which involve color names take an optional argument to
 determine the specification from which to draw color names. See :ref:`the set
@@ -34,26 +34,27 @@ raise :exc:`ValueError`.
 
 .. admonition:: **Imports and submodules**
 
-   The public, supported API of webcolors is exported from its top-level
+   The public, supported API of ``webcolors`` is exported from its top-level
    module, ``webcolors``. Although the codebase is internally organized into
    several submodules for easier maintenance, the existence, names, and
-   organization of these submodules is *not* part of webcolors' supported API
-   and cannot be relied upon.
+   organization of these submodules is *not* part of ``webcolors``' supported
+   API and cannot be relied upon.
 
-   For example: although :func:`normalize_hex` is actually implemented
-   in a submodule named ``webcolors._normalization``, it must always be
-   referred to as ``webcolors.normalize_hex``, **never** as
+   For example: although :func:`normalize_hex` is actually implemented in a
+   submodule named ``webcolors._normalization``, it must always be referred to
+   as ``webcolors.normalize_hex``, **never** as
    ``webcolors._normalization.normalize_hex``.
 
 
 Data types
 ----------
 
 Integer and percentage ``rgb()`` triplets, and HTML5 simple colors, can be
-passed to functions in webcolors as plain 3-:class:`tuple` of the appropriate
-data type. But the following :class:`~typing.NamedTuple` instances are also
-provided to represent these types more richly, and functions in webcolors which
-return triplets or simple colors will return instances of these:
+passed to functions in ``webcolors`` as plain 3-:class:`tuple` of the
+appropriate data type. But the following :class:`~typing.NamedTuple` instances
+are also provided to represent these types more richly, and functions in
+``webcolors`` which return triplets or simple colors will return instances of
+these:
 
 .. autoclass:: IntegerRGB
 .. autoclass:: PercentRGB
@@ -68,8 +69,8 @@ defined, and used throughout this module:
 Constants
 ---------
 
-Several sets of constants are provided in webcolors, for use when converting or
-identifying colors or specifications.
+Several sets of constants are provided in ``webcolors``, for use when
+converting or identifying colors or specifications.
 
 .. _spec-constants:
 
@@ -196,15 +197,15 @@ Conversions from hexadecimal color values to other formats
 .. autofunction:: hex_to_rgb_percent
 
 
-Conversions from integer `rgb()` triplets to other formats
+Conversions from integer ``rgb()`` triplets to other formats
 ------------------------------------------------------------
 
 .. autofunction:: rgb_to_name
 .. autofunction:: rgb_to_hex
 .. autofunction:: rgb_to_rgb_percent
 
 
-Conversions from percentage `rgb()` triplets to other formats
+Conversions from percentage ``rgb()`` triplets to other formats
 ---------------------------------------------------------------
 
 .. autofunction:: rgb_percent_to_name

docs/conventions.rst

@@ -6,7 +6,7 @@ Normalization and conventions
 
 Since the various formats used to specify colors in web documents do not always
 map cleanly to Python data types, and some variation is permitted in how to use
-each format in a web document, webcolors applies a set of conventions for
+each format in a web document, ``webcolors`` applies a set of conventions for
 representing color names and values, and for normalizing them.
 
 
@@ -15,17 +15,17 @@ representing color names and values, and for normalizing them.
 Python string types
 -------------------
 
-As Python 2 is no longer supported by the Python core team, webcolors now
+As Python 2 is no longer supported by the Python core team, ``webcolors`` now
 supports only Python 3, where the string type is a Unicode string. Python 3
 does still have the :class:`bytes` type, but all string arguments to functions
-in webcolors must be :class:`str` and never :class:`bytes`.
+in ``webcolors`` must be :class:`str` and never :class:`bytes`.
 
 
 Hexadecimal color values
 ------------------------
 
-For colors specified via hexadecimal values, webcolors will accept strings in
-the following formats:
+For colors specified via hexadecimal values, ``webcolors`` will accept strings
+in the following formats:
 
 * The character ``#`` followed by three hexadecimal digits, where digits A-F
   may be upper- or lowercase.
@@ -37,8 +37,8 @@ the following formats:
 
 For output which consists of a color specified via hexadecimal values, and for
 functions which perform intermediate conversion to hexadecimal before returning
-a result in another format, webcolors always normalizes such values to a string
-in the following format:
+a result in another format, ``webcolors`` always normalizes such values to a
+string in the following format:
 
 * The character ``#`` followed by six hexadecimal digits, with digits A-F
   forced to lowercase (what HTML5 designates a "valid lowercase simple color").
@@ -90,15 +90,15 @@ normalization manually if desired.
 Color names
 -----------
 
-For colors specified via predefined names, webcolors will accept strings
+For colors specified via predefined names, ``webcolors`` will accept strings
 containing names case-insensitively, so long as they contain no spaces or
 non-alphabetic characters. Thus, for example, ``"AliceBlue"`` and
 ``"aliceblue"`` are both accepted, and both will refer to the same color:
 ``rgb(240, 248, 255)``.
 
 For output which consists of a color name, and for functions which perform
 intermediate conversion to a predefined name before returning a result in
-another format, webcolors always normalizes such values to be entirely
+another format, ``webcolors`` always normalizes such values to be entirely
 lowercase.
 
 .. note:: **Spelling variants**
@@ -111,20 +111,21 @@ lowercase.
    ``"lightslategray"``/``"lightslategrey"``, ``"slategray"``/``"slategrey"``.
 
    Reversing from the hexadecimal value, integer tuple, or percent tuple to a
-   name, for these colors, requires picking one spelling, and webcolors chooses
-   the ``"gray"`` spellings for consistency with HTML 4, CSS1, and CSS2.
+   name, for these colors, requires picking one spelling, and ``webcolors``
+   chooses the ``"gray"`` spellings for consistency with HTML 4, CSS1, and
+   CSS2.
 
 
 
 Identifying sets of named colors
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-For purposes of identifying the specification from which to draw the
-selection of defined color names, webcolors uses strings naming the
-specifications, and provides :ref:`a set of constants containing the
-correct values <spec-constants>`.
+For purposes of identifying the specification from which to draw the selection
+of defined color names, ``webcolors`` uses strings naming the specifications,
+and provides :ref:`a set of constants containing the correct values
+<spec-constants>`.
 
 Note that the CSS1 named colors are not supported here, as CSS1 merely
-"suggested" a set of color names, and declined to provide values for
-them. The CSS2 "system colors" are also not represented here, as they
-had no fixed defined values and are now deprecated.
+"suggested" a set of color names, and declined to provide values for them. The
+CSS2 "system colors" are also not represented here, as they had no fixed
+defined values and are now deprecated.