Update various docstrings.

colour-science · Apr 23, 2020 · 817b1aa · 817b1aa
1 parent 6765d1d
commit 817b1aa
Show file tree

Hide file tree

Showing 9 changed files with 170 additions and 71 deletions.
diff --git a/colour/plotting/characterisation.py b/colour/plotting/characterisation.py
@@ -43,7 +43,9 @@ def plot_single_colour_checker(colour_checker='ColorChecker 2005', **kwargs):
     Parameters
     ----------
     colour_checker : unicode, optional
-        Color checker name.
+        Color checker to plot. ``colour_checker`` can be of any type or form
+        supported by the
+        :func:`colour.plotting.filter_colour_checkers` definition.
 
     Other Parameters
     ----------------
@@ -87,7 +89,9 @@ def plot_multi_colour_checkers(colour_checkers=None, **kwargs):
     Parameters
     ----------
     colour_checkers : array_like, optional
-        Color checker names, must be less than or equal to 2 names.
+        Color checker to plot, count must be less than or equal to 2.
+        ``colour_checkers`` elements can be of any type or form supported by
+        the :func:`colour.plotting.filter_colour_checkers` definition.
 
     Other Parameters
     ----------------

diff --git a/colour/plotting/colorimetry.py b/colour/plotting/colorimetry.py
@@ -75,6 +75,10 @@ def plot_single_sd(sd,
     ----------
     sd : SpectralDistribution
         Spectral distribution to plot.
+    cmfs : unicode, optional
+        Standard observer colour matching functions used for computing the
+        spectrum domain and colours. ``cmfs`` can be of any type or form
+        supported by the :func:`colour.plotting.filter_cmfs` definition.
     out_of_gamut_clipping : bool, optional
         Whether to clip out of gamut colours otherwise, the colours will be
         offset by the absolute minimal colour leading to a rendering on
@@ -88,8 +92,6 @@ def plot_single_sd(sd,
         arguments to *True* will generate a spectrum strip where each
         wavelength colour is modulated by the spectral distribution amplitude.
         The usual 5% margin above the spectral distribution is also omitted.
-    cmfs : unicode
-        Standard observer colour matching functions used for spectrum creation.
 
     Other Parameters
     ----------------
@@ -213,7 +215,9 @@ def plot_multi_sds(sds,
         of :class:`colour.MultiSpectralDistributions` class instances or a
         list of :class:`colour.SpectralDistribution` class instances.
     cmfs : unicode, optional
-        Standard observer colour matching functions used for spectrum creation.
+        Standard observer colour matching functions used for computing the
+        spectral distributions colours. ``cmfs`` can be of any type or form
+        supported by the :func:`colour.plotting.filter_cmfs` definition.
     use_sds_colours : bool, optional
         Whether to use spectral distributions colours.
     normalise_sds_colours : bool
@@ -315,7 +319,8 @@ def plot_single_cmfs(cmfs='CIE 1931 2 Degree Standard Observer', **kwargs):
     Parameters
     ----------
     cmfs : unicode, optional
-        Colour matching functions to plot.
+        Colour matching functions to plot. ``cmfs`` can be of any type or form
+        supported by the :func:`colour.plotting.filter_cmfs` definition.
 
     Other Parameters
     ----------------
@@ -359,7 +364,9 @@ def plot_multi_cmfs(cmfs=None, **kwargs):
     Parameters
     ----------
     cmfs : array_like, optional
-        Colour matching functions to plot.
+        Colour matching functions to plot. ``cmfs`` elements can be of any
+        type or form supported by the :func:`colour.plotting.filter_cmfs`
+        definition.
 
     Other Parameters
     ----------------
@@ -443,9 +450,12 @@ def plot_single_illuminant_sd(illuminant='A',
     Parameters
     ----------
     illuminant : unicode, optional
-        Factory illuminant to plot.
+        Illuminant to plot. ``illuminant`` can be of any type or form supported
+        by the :func:`colour.plotting.filter_illuminants` definition.
     cmfs : unicode, optional
-        Standard observer colour matching functions to plot.
+        Standard observer colour matching functions used for computing the
+        spectrum domain and colours. ``cmfs`` can be of any type or form
+        supported by the :func:`colour.plotting.filter_cmfs` definition.
 
     Other Parameters
     ----------------
@@ -499,7 +509,9 @@ def plot_multi_illuminant_sds(illuminants=None, **kwargs):
     Parameters
     ----------
     illuminants : array_like, optional
-        Factory illuminants to plot.
+        Illuminants to plot. ``illuminants`` elements can be of any type or
+        form supported by the :func:`colour.plotting.filter_illuminants`
+        definition.
 
     Other Parameters
     ----------------
@@ -559,7 +571,9 @@ def plot_visible_spectrum(cmfs='CIE 1931 2 Degree Standard Observer',
     Parameters
     ----------
     cmfs : unicode, optional
-        Standard observer colour matching functions used for spectrum creation.
+        Standard observer colour matching functions used for computing the
+        spectrum domain and colours. ``cmfs`` can be of any type or form
+        supported by the :func:`colour.plotting.filter_cmfs` definition.
     out_of_gamut_clipping : bool, optional
         Whether to clip out of gamut colours otherwise, the colours will be
         offset by the absolute minimal colour leading to a rendering on
@@ -629,7 +643,8 @@ def plot_single_lightness_function(function='CIE 1976', **kwargs):
     Parameters
     ----------
     function : unicode, optional
-        *Lightness* function to plot.
+        *Lightness* function to plot. ``function`` can be of any type or form
+        supported by the :func:`colour.plotting.filter_passthrough` definition.
 
     Other Parameters
     ----------------
@@ -669,7 +684,9 @@ def plot_multi_lightness_functions(functions=None, **kwargs):
     Parameters
     ----------
     functions : array_like, optional
-        *Lightness* functions to plot.
+        *Lightness* functions to plot. ``functions`` elements can be of any
+        type or form supported by the
+        :func:`colour.plotting.filter_passthrough` definition.
 
     Other Parameters
     ----------------
@@ -762,7 +779,9 @@ def plot_multi_luminance_functions(functions=None, **kwargs):
     Parameters
     ----------
     functions : array_like, optional
-        *Luminance* functions to plot.
+        *Luminance* functions to plot. ``functions`` elements can be of any
+        type or form supported by the
+        :func:`colour.plotting.filter_passthrough` definition.
 
     Other Parameters
     ----------------
@@ -821,7 +840,9 @@ def plot_blackbody_spectral_radiance(
     temperature : numeric, optional
         Blackbody temperature.
     cmfs : unicode, optional
-        Standard observer colour matching functions.
+        Standard observer colour matching functions used for computing the
+        spectrum domain and colours. ``cmfs`` can be of any type or form
+        supported by the :func:`colour.plotting.filter_cmfs` definition.
     blackbody : unicode, optional
         Blackbody name.
 
@@ -913,7 +934,9 @@ def plot_blackbody_colours(
     shape : SpectralShape, optional
         Spectral shape to use as plot boundaries.
     cmfs : unicode, optional
-        Standard observer colour matching functions.
+        Standard observer colour matching functions used for computing the
+        blackbody colours. ``cmfs`` can be of any type or form supported by the
+        :func:`colour.plotting.filter_cmfs` definition.
 
     Other Parameters
     ----------------

diff --git a/colour/plotting/common.py b/colour/plotting/common.py
@@ -695,14 +695,22 @@ class instances whose type is one of the mapping element types.
 
     This definition allows passing custom but compatible objects to the various
     plotting definitions that by default expect the key from a dataset element.
+
     For example, a typical call to :func:`colour.plotting.\
-plot_multi_illuminant_sds` definition is as follows:
+plot_multi_illuminant_sds` definition with a regex pattern automatically
+    anchored at boundaries by default is as follows:
 
     >>> import colour
     >>> colour.plotting.plot_multi_illuminant_sds(['A'])
     ... # doctest: +SKIP
 
-    But it is also possible to pass a custom spectral distribution as follows:
+    Here, `'A'` is by default anchored at boundaries and transformed into
+    `'^A$'`. Note that because it is a regex pattern, special characters such
+    as parenthesis must be escaped: `'Adobe RGB (1998)'` must be written
+    `'Adobe RGB \\(1998\\)'` instead.
+
+    With the previous example, t is also possible to pass a custom spectral
+    distribution as follows:
 
     >>> data = {
     ...     500: 0.0651,
@@ -812,7 +820,9 @@ def filter_RGB_colourspaces(filterers,
     filterers : unicode or RGB_Colourspace or array_like
         Filterer or :class:`colour.RGB_Colourspace` class instance (which is
         passed through directly if its type is one of the mapping element
-        types) or list of filterers.
+        types) or list of filterers. ``filterers`` elements can also be of any
+        form supported by the :func:`colour.plotting.filter_passthrough`
+        definition.
     anchors : bool, optional
         Whether to use Regex line anchors, i.e. *^* and *$* are added,
         surrounding the filterers patterns.
@@ -846,7 +856,9 @@ def filter_cmfs(filterers,
         :class:`colour.RGB_ColourMatchingFunctions` or
         :class:`colour.XYZ_ColourMatchingFunctions` class instance (which is
         passed through directly if its type is one of the mapping element
-        types) or list of filterers.
+        types) or list of filterers. ``filterers`` elements can also be of any
+        form supported by the :func:`colour.plotting.filter_passthrough`
+        definition.
     anchors : bool, optional
         Whether to use Regex line anchors, i.e. *^* and *$* are added,
         surrounding the filterers patterns.
@@ -877,7 +889,9 @@ def filter_illuminants(filterers,
     filterers : unicode or SpectralDistribution or array_like
         Filterer or :class:`colour.SpectralDistribution` class instance
         (which is passed through directly if its type is one of the mapping
-        element types) or list of filterers.
+        element types) or list of filterers. ``filterers`` elements can also be
+        of any form supported by the :func:`colour.plotting.filter_passthrough`
+        definition.
     anchors : bool, optional
         Whether to use Regex line anchors, i.e. *^* and *$* are added,
         surrounding the filterers patterns.
@@ -917,7 +931,9 @@ def filter_colour_checkers(filterers,
     filterers : unicode or ColourChecker or array_like
         Filterer or :class:`colour.characterisation.ColourChecker` class
         instance (which is passed through directly if its type is one of the
-        mapping element types) or list of filterers.
+        mapping element types) or list of filterers. ``filterers`` elements
+        can also be of any form supported by the
+        :func:`colour.plotting.filter_passthrough` definition.
     anchors : bool, optional
         Whether to use Regex line anchors, i.e. *^* and *$* are added,
         surrounding the filterers patterns.

diff --git a/colour/plotting/diagrams.py b/colour/plotting/diagrams.py
@@ -61,8 +61,9 @@ def plot_spectral_locus(cmfs='CIE 1931 2 Degree Standard Observer',
     Parameters
     ----------
     cmfs : unicode, optional
-        Standard observer colour matching functions defining the
-        *Spectral Locus*.
+        Standard observer colour matching functions used for computing the
+        spectral locus boundaries. ``cmfs`` can be of any type or form
+        supported by the :func:`colour.plotting.filter_cmfs` definition.
     spectral_locus_colours : array_like or unicode, optional
         *Spectral Locus* colours, if ``spectral_locus_colours`` is set to
         *RGB*, the colours will be computed according to the corresponding
@@ -232,8 +233,9 @@ def plot_chromaticity_diagram_colours(
     diagram_clipping_path : array_like, optional
         Path of points used to clip the *Chromaticity Diagram* colours.
     cmfs : unicode, optional
-        Standard observer colour matching functions used for
-        *Chromaticity Diagram* bounds.
+        Standard observer colour matching functions used for computing the
+        spectral locus boundaries. ``cmfs`` can be of any type or form
+        supported by the :func:`colour.plotting.filter_cmfs` definition.
     method : unicode, optional
         **{'CIE 1931', 'CIE 1960 UCS', 'CIE 1976 UCS'}**,
         *Chromaticity Diagram* method.
@@ -332,8 +334,9 @@ def plot_chromaticity_diagram(cmfs='CIE 1931 2 Degree Standard Observer',
     Parameters
     ----------
     cmfs : unicode, optional
-        Standard observer colour matching functions used for
-        *Chromaticity Diagram* bounds.
+        Standard observer colour matching functions used for computing the
+        spectral locus boundaries. ``cmfs`` can be of any type or form
+        supported by the :func:`colour.plotting.filter_cmfs` definition.
     show_diagram_colours : bool, optional
         Whether to display the *Chromaticity Diagram* background colours.
     show_spectral_locus : bool, optional
@@ -429,8 +432,9 @@ def plot_chromaticity_diagram_CIE1931(
     Parameters
     ----------
     cmfs : unicode, optional
-        Standard observer colour matching functions used for
-        *Chromaticity Diagram* bounds.
+        Standard observer colour matching functions used for computing the
+        spectral locus boundaries. ``cmfs`` can be of any type or form
+        supported by the :func:`colour.plotting.filter_cmfs` definition.
     show_diagram_colours : bool, optional
         Whether to display the *Chromaticity Diagram* background colours.
     show_spectral_locus : bool, optional
@@ -479,8 +483,9 @@ def plot_chromaticity_diagram_CIE1960UCS(
     Parameters
     ----------
     cmfs : unicode, optional
-        Standard observer colour matching functions used for
-        *Chromaticity Diagram* bounds.
+        Standard observer colour matching functions used for computing the
+        spectral locus boundaries. ``cmfs`` can be of any type or form
+        supported by the :func:`colour.plotting.filter_cmfs` definition.
     show_diagram_colours : bool, optional
         Whether to display the *Chromaticity Diagram* background colours.
     show_spectral_locus : bool, optional
@@ -529,8 +534,9 @@ def plot_chromaticity_diagram_CIE1976UCS(
     Parameters
     ----------
     cmfs : unicode, optional
-        Standard observer colour matching functions used for
-        *Chromaticity Diagram* bounds.
+        Standard observer colour matching functions used for computing the
+        spectral locus boundaries. ``cmfs`` can be of any type or form
+        supported by the :func:`colour.plotting.filter_cmfs` definition.
     show_diagram_colours : bool, optional
         Whether to display the *Chromaticity Diagram* background colours.
     show_spectral_locus : bool, optional
@@ -588,8 +594,9 @@ def plot_sds_in_chromaticity_diagram(
         of :class:`colour.MultiSpectralDistributions` class instances or a
         list of :class:`colour.SpectralDistribution` class instances.
     cmfs : unicode, optional
-        Standard observer colour matching functions used for
-        *Chromaticity Diagram* bounds.
+        Standard observer colour matching functions used for computing the
+        spectral locus boundaries. ``cmfs`` can be of any type or form
+        supported by the :func:`colour.plotting.filter_cmfs` definition.
     annotate_kwargs : dict or array_like, optional
         Parameters for the :func:`plt.annotate` definition, used to annotate
         the resulting chromaticity coordinates with their respective spectral
@@ -763,8 +770,9 @@ class instance, a list of :class:`colour.MultiSpectralDistributions`
         class instances or a list of :class:`colour.SpectralDistribution` class
         instances.
     cmfs : unicode, optional
-        Standard observer colour matching functions used for
-        *Chromaticity Diagram* bounds.
+        Standard observer colour matching functions used for computing the
+        spectral locus boundaries. ``cmfs`` can be of any type or form
+        supported by the :func:`colour.plotting.filter_cmfs` definition.
     annotate_kwargs : dict or array_like, optional
         Parameters for the :func:`plt.annotate` definition, used to annotate
         the resulting chromaticity coordinates with their respective spectral
@@ -838,8 +846,9 @@ class instance, a list of :class:`colour.MultiSpectralDistributions`
         class instances or a list of :class:`colour.SpectralDistribution` class
         instances.
     cmfs : unicode, optional
-        Standard observer colour matching functions used for
-        *Chromaticity Diagram* bounds.
+        Standard observer colour matching functions used for computing the
+        spectral locus boundaries. ``cmfs`` can be of any type or form
+        supported by the :func:`colour.plotting.filter_cmfs` definition.
     annotate_kwargs : dict or array_like, optional
         Parameters for the :func:`plt.annotate` definition, used to annotate
         the resulting chromaticity coordinates with their respective spectral
@@ -914,8 +923,9 @@ class instance, a list of :class:`colour.MultiSpectralDistributions`
         class instances or a list of :class:`colour.SpectralDistribution` class
         instances.
     cmfs : unicode, optional
-        Standard observer colour matching functions used for
-        *Chromaticity Diagram* bounds.
+        Standard observer colour matching functions used for computing the
+        spectral locus boundaries. ``cmfs`` can be of any type or form
+        supported by the :func:`colour.plotting.filter_cmfs` definition.
     annotate_kwargs : dict or array_like, optional
         Parameters for the :func:`plt.annotate` definition, used to annotate
         the resulting chromaticity coordinates with their respective spectral