feat: enhance documentation with new examples and images for Matplotlib sizing

Author: c0rychu

docs/api.md

@@ -2,6 +2,5 @@
 
 This section is rendered from the package's type hints and NumPy-style docstrings using [`mkdocstrings`](https://mkdocstrings.github.io/). Update the inline documentation in `src/physics_plot/` and rebuild the docs to refresh the content.
 
-## Legend Containers
+::: physics_plot
 
-::: physics_plot.utils.Handles

docs/examples.md

@@ -2,6 +2,12 @@
 
 See the [examples directory on GitHub](https://github.com/c0rychu/physics-plot/tree/main/examples).
 
+
+```python title="examples/bode-plot.py"
+--8<-- "examples/bode-plot.py"
+```
+![Bode plot example](https://raw.githubusercontent.com/c0rychu/physics-plot/main/examples/bode-plot%402x.png)
+
 <!-- Physics Plot ships with runnable demos so you can see how the style sheet and utilities behave on real data. Clone the repository locally, install the dependencies, and run the scripts from the project root.
 
 ## Bode Plot

docs/mpl/mpl-size-lg.png

@@ -0,0 +1,14 @@
+The first and the most important trick when plotting with Matplotlib is to set the figure size appropriately.
+If you want to increase the font size and line width everywhere in the figure, the easiest way is to **decrease the figure size**!
+
+!!! tip
+    This is counter-intuitive at first, but it works because Matplotlib scales text elements (like axis labels, tick labels, legends, etc.) relative to the figure size.
+    So a smaller figure size results in larger text elements, making them more readable.
+
+
+```python
+--8<-- "mpl/mpl-size.py"
+```
+
+![small size](mpl-size-sm.png) 
+![large size](mpl-size-lg.png)

docs/mpl/mpl-size-sm.png

@@ -0,0 +1,25 @@
+import matplotlib.pyplot as plt
+import numpy as np
+
+plt.style.use("physics_plot.pp_base")
+
+fig, ax = plt.subplots(figsize=(4, 2), constrained_layout=True)
+x = np.linspace(0, 10, 100)
+y = np.sin(x)
+ax.plot(x, y, label="Sine Wave")
+ax.set_ylabel(r"$y(x)$")
+ax.set_xlabel(r"$x$")
+ax.legend(loc="upper right")
+fig.suptitle(r"\texttt{figsize=(4, 2)}")
+fig.savefig("mpl-size-sm.png")
+
+
+fig, ax = plt.subplots(figsize=(10, 5), constrained_layout=True)
+x = np.linspace(0, 10, 100)
+y = np.sin(x)
+ax.plot(x, y, label="Sine Wave")
+ax.set_ylabel(r"$y(x)$")
+ax.set_xlabel(r"$x$")
+ax.legend(loc="upper right")
+fig.suptitle(r"\texttt{figsize=(10, 5)}")
+fig.savefig("mpl-size-lg.png")

docs/mpl/mpl-size.md

@@ -47,16 +47,19 @@ markdown_extensions:
   - pymdownx.details
   - pymdownx.highlight
   - pymdownx.inlinehilite
-  - pymdownx.snippets
+  - pymdownx.snippets:
+      base_path: [docs, .]
   - pymdownx.superfences
 plugins:
-  - search
   - mkdocstrings:
       handlers:
         python:
+          paths: [src]
           options:
-            docstring_style: numpy
+            show_root_heading: true
+            show_submodules: true
             show_source: true
+            docstring_style: numpy
             members_order: alphabetical
 extra:
   social: