diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index bd7ce008b..4b9a41db3 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -47,3 +47,9 @@ repos: hooks: - id: prettier exclude: config-aces-reference.ocio.yaml + - repo: https://github.com/pre-commit/pygrep-hooks + rev: "v1.10.0" + hooks: + - id: rst-backticks + - id: rst-directive-colons + - id: rst-inline-touching-normal diff --git a/docs/advanced.rst b/docs/advanced.rst index 801467d41..300515a11 100644 --- a/docs/advanced.rst +++ b/docs/advanced.rst @@ -9,16 +9,16 @@ Environment Various environment variables can be used to modify **Colour** behaviour at runtime: -- `COLOUR_SCIENCE__DEFAULT_INT_DTYPE`: Set the default integer dtype for +- ``COLOUR_SCIENCE__DEFAULT_INT_DTYPE``: Set the default integer dtype for most of **Colour** computations. Possible values are `int32` and `int64` (default). Changing the integer dtype *will almost certainly break* **Colour**! *With great power comes great responsibility*. -- `COLOUR_SCIENCE__DEFAULT_FLOAT_DTYPE`: Set the float dtype for most of +- ``COLOUR_SCIENCE__DEFAULT_FLOAT_DTYPE``: Set the float dtype for most of **Colour** computations. Possible values are `float16`, `float32` and `float64` (default). Changing the float dtype might result in various **Colour** `functionality breaking entirely `__. *With great power comes great responsibility*. -- `COLOUR_SCIENCE__COLOUR__SHOW_WARNINGS_WITH_TRACEBACK`: Result in the +- ``COLOUR_SCIENCE__COLOUR__SHOW_WARNINGS_WITH_TRACEBACK``: Result in the :func:`warnings.showwarning` definition to be replaced with the :func:`colour.utilities.show_warning` definition and thus providing complete traceback from the point where the warning occurred. @@ -29,7 +29,7 @@ Caching **Colour** uses various internal caches to improve speed and prevent redundant processes, notably for spectral related computations. -The internal caches are managed with the `colour.utilities.CACHE_REGISTRY` +The internal caches are managed with the :attr:`colour.utilities.CACHE_REGISTRY` cache registry object: .. code-block:: python @@ -53,7 +53,7 @@ cache registry object: 'colour.volume.spectrum._CACHE_OUTER_SURFACE_XYZ': '0 item(s)', 'colour.volume.spectrum._CACHE_OUTER_SURFACE_XYZ_POINTS': '0 item(s)'} -See `colour.utilities.CacheRegistry` class documentation for more information +See :class:`colour.utilities.CacheRegistry` class documentation for more information on how to manage the cache registry. Using Colour without Scipy diff --git a/docs/basics.rst b/docs/basics.rst index b8160b8b8..99d936f4b 100644 --- a/docs/basics.rst +++ b/docs/basics.rst @@ -415,24 +415,24 @@ Domain-Range Scales **Colour** adopts 4 main input domains and output ranges: -- *Scalars* usually in domain-range `[0, 1]` (or `[0, 10]` for +- *Scalars* usually in domain-range ``[0, 1]`` (or ``[0, 10]`` for *Munsell Value*). -- *Percentages* usually in domain-range `[0, 100]`. -- *Degrees* usually in domain-range `[0, 360]`. -- *Integers* usually in domain-range `[0, 2**n -1]` where `n` is the bit +- *Percentages* usually in domain-range ``[0, 100]``. +- *Degrees* usually in domain-range ``[0, 360]``. +- *Integers* usually in domain-range ``[0, 2**n -1]`` where ``n`` is the bit depth. It is error prone but it is also a direct consequence of the inconsistency of the colour science field itself. We have discussed at length about this and we -were leaning toward normalisation of the whole API to domain-range `[0, 1]`, we -never committed for reasons highlighted by the following points: +were leaning toward normalisation of the whole API to domain-range ``[0, 1]``, +we never committed for reasons highlighted by the following points: - Colour Scientist performing computations related to Munsell Renotation System would be very surprised if the output *Munsell Value* was in range - `[0, 1]` or `[0, 100]`. + ``[0, 1]`` or ``[0, 100]``. - A Visual Effect Industry artist would be astonished to find out that conversion from *CIE XYZ* to *sRGB* was yielding values in range - `[0, 100]`. + ``[0, 100]``. However benefits of having a consistent and predictable domain-range scale are numerous thus with `Colour 0.3.12 `__ @@ -446,25 +446,25 @@ Scale - Reference the implemented reference, i.e. paper, publication, etc.., domain-range scale. The **'Reference'** domain-range scale is inconsistent, e.g. colour appearance -models, spectral conversions are typically in domain-range `[0, 100]` while RGB -models will operate in domain-range `[0, 1]`. Some objects, e.g. -:func:`colour.colorimetry.lightness_Fairchild2011` definition have mismatched -domain-range: input domain `[0, 1]` and output range `[0, 100]`. +models, spectral conversions are typically in domain-range ``[0, 100]`` while RGB +models will operate in domain-range ``[0, 1]``. Some objects, e.g. +:func:``colour.colorimetry.lightness_Fairchild2011`` definition have mismatched +domain-range: input domain ``[0, 1]`` and output range ``[0, 100]``. Scale - 1 ~~~~~~~~~ **'1'** is a domain-range scale converting all the relevant objects from -**Colour** public API to domain-range `[0, 1]`: +**Colour** public API to domain-range ``[0, 1]``: -- *Scalars* in domain-range `[0, 10]`, e.g *Munsell Value* are +- *Scalars* in domain-range ``[0, 10]``, e.g *Munsell Value* are scaled by *10*. -- *Percentages* in domain-range `[0, 100]` are scaled by *100*. -- *Degrees* in domain-range `[0, 360]` are scaled by *360*. -- *Integers* in domain-range `[0, 2**n -1]` where `n` is the bit +- *Percentages* in domain-range ``[0, 100]`` are scaled by *100*. +- *Degrees* in domain-range ``[0, 360]`` are scaled by *360*. +- *Integers* in domain-range ``[0, 2**n -1]`` where ``n`` is the bit depth are scaled by *2**n -1*. -- *Dimensionless* values are unaffected and are indicated with `DN`. -- *Unaffected* values are unaffected and are indicated with `UN`. +- *Dimensionless* values are unaffected and are indicated with ``DN``. +- *Unaffected* values are unaffected and are indicated with ``UN``. .. warning:: @@ -573,12 +573,12 @@ would result in unexpected values and a warning in that case: Setting the **'1'** domain-range scale has the following effect on the :func:`colour.adaptation.chromatic_adaptation_CIE1994` definition: -As it expects values in domain `[0, 100]`, scaling occurs and the +As it expects values in domain ``[0, 100]``, scaling occurs and the relevant input values, i.e. the values listed in the domain table, ``XYZ_1`` -and ``Y_o`` are converted from domain `[0, 1]` to domain `[0, 100]` by +and ``Y_o`` are converted from domain ``[0, 1]`` to domain ``[0, 100]`` by :func:`colour.utilities.to_domain_100` definition and conversely -return value ``XYZ_2`` is converted from range `[0, 100]` to range `[0, 1]` by -:func:`colour.utilities.from_range_100` definition. +return value ``XYZ_2`` is converted from range ``[0, 100]`` to range ``[0, 1]`` +by :func:`colour.utilities.from_range_100` definition. A convenient alternative to the :func:`colour.set_domain_range_scale` definition is the :class:`colour.domain_range_scale` context manager and