feat: add color examples and documentation for Matplotlib styles; include named, default, and colorblind palettes

Author: c0rychu

docs/color/color-CN.png

@@ -0,0 +1,16 @@
+import matplotlib.pyplot as plt
+import numpy as np
+
+plt.style.use(["physics_plot.pp_base", "physics_plot.colors.ggplot"])
+
+t = np.linspace(0, 10, 100)
+y = np.sin(t)
+
+fig, ax = plt.subplots(figsize=(4, 2), constrained_layout=True)
+ax.plot(t, y, "C0", label="C0")
+ax.plot(t, y + 1, "C4", label="C4")
+ax.set_ylabel(r"$y(t)$")
+ax.set_xlabel(r"Time $t$ [s]")
+ax.legend(loc="upper right")
+fig.suptitle(r"\texttt{ggplot} - color (from Matplotlib)")
+fig.savefig("color-CN.png")

docs/color/color-CN.py

@@ -0,0 +1,20 @@
+import matplotlib.pyplot as plt
+import numpy as np
+
+t = np.linspace(0, 10, 100)
+y = np.sin(t)
+
+with plt.style.context("physics_plot.pp_base"):
+    fig, ax = plt.subplots(figsize=(4, 2.5), constrained_layout=True)
+    ax.plot(t, y - 0.0, "r", label="r (red)")
+    ax.plot(t, y - 0.3, "k", label="k (black)")
+    ax.plot(t, y - 0.6, "b", label="b (blue)")
+    ax.plot(t, y - 0.9, "g", label="g (green)")
+    ax.plot(t, y - 1.2, "c", label="c (cyan)")
+    ax.plot(t, y - 1.5, "m", label="m (magenta)")
+
+    ax.set_ylabel(r"$y(t)$")
+    ax.set_xlabel(r"Time $t$ [s]")
+    ax.legend(loc="upper right")
+    fig.suptitle(r"Named colors (from Matplotlib)")
+    fig.savefig("color-named.png")

docs/color/color-colorblind.png

@@ -0,0 +1,58 @@
+There are several convenient ways to specify colors in Matplotlib.
+
+## Named colors
+
+List of named colors is documented in the [Matplotlib documentation - Named Colors](https://matplotlib.org/stable/gallery/color/named_colors.html).
+A simple example using named colors is shown below.
+
+```python
+--8<-- "docs/color/color-named.py"
+```
+![Named colors example](color-named.png)
+
+
+## Color palettes
+If you do not specify a color, Matplotlib will cycle through a set of colors. In addition to the default color cycle, we provide a few additional color palettes: `ggplot`[^ggplot] and `colorblind`[^colorblind] gathered from the Matplotlib and seaborn.
+
+To use a different color palette in combination with the Physics Plot style sheet, just combine the style sheets as a list. For example, to use the `physics_plot.colors.ggplot` color palette globally:
+```python
+import matplotlib.pyplot as plt
+
+plt.style.use(["physics_plot.pp_base", "physics_plot.colors.ggplot"])
+
+# ... your plotting code here ...
+```
+or locally with a context manager:
+```python
+import matplotlib.pyplot as plt
+
+with plt.style.context(["physics_plot.pp_base", "physics_plot.colors.ggplot"]):
+    # ... your plotting code here ...
+```
+
+The available color palettes shipped with Physics Plot are: `physics_plot.colors.ggplot` and `physics_plot.colors.colorblind`, but you can also combine with any other Matplotlib style sheets.
+
+---
+
+Following is an example that demonstrates the different color cycles:
+```python linenums="1" hl_lines="7 18 29"
+--8<-- "docs/color/color.py"
+```
+
+![Default color cycle example](color-default.png)
+![ggplot color cycle example](color-ggplot.png)
+![colorblind color cycle example](color-colorblind.png)
+
+
+!!! tip
+    It is also possible to specify which color among the current color cycle to choose by using the `C0`, `C1`, ... notation.
+    For instance,
+    ```python linenums="1" hl_lines="10 11"
+    ---8<-- "docs/color/color-CN.py"
+    ```
+    ![CN color example](color-CN.png)
+
+
+[^ggplot]: The `ggplot` color palette is taken from Matplotlib at [https://github.com/matplotlib/matplotlib/blob/v3.10.7/lib/matplotlib/mpl-data/stylelib/ggplot.mplstyle](https://github.com/matplotlib/matplotlib/blob/v3.10.7/lib/matplotlib/mpl-data/stylelib/ggplot.mplstyle).
+
+[^colorblind]: The `colorblind` palette is taken from seaborn at [https://github.com/mwaskom/seaborn/blob/v0.13/seaborn/palettes.py](https://github.com/mwaskom/seaborn/blob/v0.13/seaborn/palettes.py).

docs/color/color-default.png

@@ -0,0 +1,37 @@
+import matplotlib.pyplot as plt
+import numpy as np
+
+t = np.linspace(0, 10, 100)
+y = np.sin(t)
+
+with plt.style.context("physics_plot.pp_base"):
+    fig, ax = plt.subplots(figsize=(4, 2), constrained_layout=True)
+    for i, offset in enumerate(np.linspace(0, 2, 5)):
+        ax.plot(t, y - offset, label=f"C{i}")
+    ax.set_ylabel(r"$y(t)$")
+    ax.set_xlabel(r"Time $t$ [s]")
+    ax.legend(loc="upper right")
+    fig.suptitle(r"Default color (from Matplotlib)")
+    fig.savefig("color-default.png")
+
+
+with plt.style.context(["physics_plot.pp_base", "physics_plot.colors.ggplot"]):
+    fig, ax = plt.subplots(figsize=(4, 2), constrained_layout=True)
+    for i, offset in enumerate(np.linspace(0, 2, 5)):
+        ax.plot(t, y - offset, label=f"C{i}")
+    ax.set_ylabel(r"$y(t)$")
+    ax.set_xlabel(r"Time $t$ [s]")
+    ax.legend(loc="upper right")
+    fig.suptitle(r"\texttt{ggplot} - color (from Matplotlib)")
+    fig.savefig("color-ggplot.png")
+
+
+with plt.style.context(["physics_plot.pp_base", "physics_plot.colors.colorblind"]):
+    fig, ax = plt.subplots(figsize=(4, 2), constrained_layout=True)
+    for i, offset in enumerate(np.linspace(0, 2, 5)):
+        ax.plot(t, y - offset, label=f"C{i}")
+    ax.set_ylabel(r"$y(t)$")
+    ax.set_xlabel(r"Time $t$ [s]")
+    ax.legend(loc="upper right")
+    fig.suptitle(r"\texttt{colorblind} - color (from Seaborn)")
+    fig.savefig("color-colorblind.png")

docs/color/color-ggplot.png

@@ -48,4 +48,4 @@ with plt.style.context("physics_plot.pp_base"):
 Yes! That's it! You are now ready to create beautiful, publication-quality plots with minimal effort using the `physics-plot` style. Enjoy plotting!
 
 
-[^mplstyle]: Matplotlib style sheets (`.mplstyle` files) are configuration files that define the default appearance of plots created with Matplotlib. They allow users to customize various aspects of plot aesthetics, such as colors, fonts, line styles, and more, by specifying these settings in a structured format. See [Matplotlib Style Sheets Reference](https://matplotlib.org/stable/gallery/style_sheets/style_sheets_reference.html) for more details.
+[^mplstyle]: Matplotlib style sheets (`.mplstyle` files) are configuration files that define the default appearance of plots created with Matplotlib. They allow users to customize various aspects of plot aesthetics, such as colors, fonts, line styles, and more, by specifying these settings in a structured format. See [Matplotlib Style Sheets Reference](https://matplotlib.org/stable/gallery/style_sheets/style_sheets_reference.html) for more details. Also, a default template can be found in the [Matplotlib documentation - Customizing Matplotlib with style sheets and rcParams](https://matplotlib.org/stable/users/explain/customizing.html#the-default-matplotlibrc-file) and its [source](https://github.com/matplotlib/matplotlib/blob/main/lib/matplotlib/mpl-data/matplotlibrc). Finally, several built-in `.mplstyle` files can be found [here](https://github.com/matplotlib/matplotlib/tree/main/lib/matplotlib/mpl-data/stylelib).