add docs

Author: c0rychu

.github/workflows/docs.yml

@@ -0,0 +1,29 @@
+name: docs 
+on:
+  push:
+    branches:
+      - master 
+      - main
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV 
+      - uses: actions/cache@v4
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: ~/.cache 
+          restore-keys: |
+            mkdocs-material-
+      - run: pip install mkdocs-material mkdocstrings[python]
+      - run: mkdocs gh-deploy --force

Makefile

@@ -0,0 +1,2 @@
+run-local-mkdocs-server:
+	uv run mkdocs serve

docs/api.md

@@ -0,0 +1,7 @@
+# API Reference
+
+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.utils.Handles

docs/development.md

@@ -0,0 +1,48 @@
+<!-- # Development
+
+This guide outlines how to set up a local development environment, run checks, and contribute improvements to Physics Plot.
+
+## Environment Setup
+
+```bash
+uv sync --group dev
+```
+
+The command installs runtime dependencies along with development tooling such as Ruff and Black.
+
+## Quality Gates
+
+- `uv run ruff check src` keeps imports sorted and enforces the style guide.
+- `uv run black --check src` validates formatting (run without `--check` to auto-format).
+- `uv run pytest` executes the test suite once it exists.
+
+Run the commands before opening a pull request so CI stays green.
+
+## Visual Regression Checklist
+
+1. Rebuild figures under `examples/` (start with the Bode plot CLI).
+2. Compare the generated images against the versions committed to the repository.
+3. Document notable deltas in the pull request description and attach screenshots.
+
+## Documentation
+
+The documentation is built with MkDocs Material:
+
+```bash
+uv run mkdocs serve
+```
+
+The command starts a live-reloading preview at `http://127.0.0.1:8000`. Commit relevant doc updates alongside code changes to keep users informed.
+
+!!! tip
+    The project uses `mkdocstrings` to render API docs from docstrings. If you manage dependencies manually, install `mkdocstrings[python]` in addition to `mkdocs-material`.
+
+## Releasing
+
+1. Bump the version in `pyproject.toml`.
+2. Regenerate `uv.lock` if dependencies changed (`uv lock --upgrade-package physics-plot`).
+3. Build the distribution with `uv build`.
+4. Publish via `uv publish` or `twine upload dist/*`.
+
+Coordinate releases through GitHub issues so maintainers can review changes and test across platforms. -->
+

docs/examples.md

@@ -0,0 +1,35 @@
+# Examples
+
+See the [examples directory on GitHub](https://github.com/c0rychu/physics-plot/tree/main/examples).
+
+<!-- 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
+
+```bash
+uv run python examples/bode-plot.py
+```
+
+The script generates a two-panel magnitude/phase plot for a first-order low-pass filter:
+
+![Bode plot example](https://raw.githubusercontent.com/c0rychu/physics-plot/main/examples/bode-plot%402x.png)
+
+Look for the balanced serif typography, synchronised axis limits, and consistent legend placement driven by the default style.
+
+## Violin Plot
+
+Open `examples/violin-plot.ipynb` in JupyterLab or VS Code and execute the cells:
+
+The notebook demonstrates using `physics_plot.Handles` to build legend entries for violin plots that otherwise omit labels.
+
+![Violin plot example](https://raw.githubusercontent.com/c0rychu/physics-plot/main/examples/violin-plot%402x.png)
+
+!!! tip
+    Capture before/after screenshots when you tweak the style sheet or utilities. Attach them to issues or pull requests to document visual changes.
+
+## Your Own Figures
+
+- Swap in your data but keep the script structure to validate visual regressions quickly.
+- Use the examples as smoke tests by running them after style tweaks; unexpected exceptions often reveal mismatched dependencies or missing fonts.
+- Consider adding new examples that cover edge cases (e.g., log scales, multiple axes) if you find gaps. Place supporting assets under `examples/` so contributors can reproduce the output.
+ -->

docs/fig/bode-plot@2x.png

@@ -0,0 +1,37 @@
+import matplotlib.pyplot as plt
+import numpy as np
+
+
+def sine_gaussian(t, f0, sigma, t0=0, A=1):
+    return (
+        A
+        * np.exp(-((t - t0) ** 2) / (2 * sigma**2))
+        * np.sin(2 * np.pi * f0 * (t - t0))
+    )
+
+
+t = np.linspace(-0.01, 0.01, 2000)
+y = sine_gaussian(t, f0=300, t0=-0.002, sigma=0.002)
+
+with plt.style.context("physics_plot.pp_base"):
+    plt.figure()
+    plt.plot(t, y, label="offset = 0")
+    plt.plot(t, y - 0.5, label="offset = -0.5")
+    plt.plot(t, y - 1, label="offset = -1")
+    plt.legend(loc="upper right")
+    plt.title(r"$\texttt{physics_plot}$ style")
+    plt.xlabel("Time [s]")
+    plt.ylabel("Amplitude")
+    plt.tight_layout()
+    plt.savefig("with-pp@2x.png")
+
+plt.figure()
+plt.plot(t, y, label="offset = 0")
+plt.plot(t, y - 0.5, label="offset = -0.5")
+plt.plot(t, y - 1, label="offset = -1")
+plt.legend(loc="upper right")
+plt.title("Matplotlib default style")
+plt.xlabel("Time [s]")
+plt.ylabel("Amplitude")
+plt.tight_layout()
+plt.savefig("without-pp@2x.png", dpi=600)

docs/fig/compare-sg.py

@@ -0,0 +1,69 @@
+import matplotlib.pyplot as plt
+import numpy as np
+
+
+# Functions for example plot
+def db(x):
+    return 20.0 * np.log10(x)
+
+
+def model(f):
+    return 10.0 / (f - 1.0j * 10)
+
+
+# Plot with physics_plot style
+with plt.style.context("physics_plot.pp_base"):
+    fig, (ax_m, ax_p) = plt.subplots(
+        nrows=2, ncols=1, figsize=(5, 3.5), constrained_layout=True
+    )
+    fig.suptitle(r"Low Pass Filter ($\texttt{physics_plot}$ style)")
+    f = np.logspace(0, 3, 1000)
+
+    # Magnitude
+    ax_m.semilogx(f, db(np.abs(model(f))), "r", label="LPF")
+    ax_m.set_xlim(1e0, 1e3)
+    ax_m.set_ylabel("Magnitude [dB]")
+    ax_m.grid(visible=True, which="major")
+    ax_m.grid(visible=True, which="minor", linestyle=":")
+    ax_m.legend(loc=1)
+
+    # Phase
+    ax_p.semilogx(f, np.angle(model(f), deg=True), "r", label="LPF")
+    ax_p.set_xlim(1e0, 1e3)
+    ax_p.set_ylim(0, 90)
+    ax_p.set_xlabel("Frequency [Hz]")
+    ax_p.set_ylabel("Phase [deg]")
+    ax_p.grid(visible=True, which="major")
+    ax_p.grid(visible=True, which="minor", linestyle=":")
+    ax_p.legend(loc=1)
+
+    # fig.savefig("with-pp@2x.png")
+    fig.savefig("bode-plot@2x.png")
+
+
+# # Plot without physics_plot style
+# fig, (ax_m, ax_p) = plt.subplots(
+#     nrows=2, ncols=1, figsize=(5, 3.5), constrained_layout=True
+# )
+# fig.suptitle("Low Pass Filter (Matplotlib default style)")
+# f = np.logspace(0, 3, 1000)
+
+# # Magnitude
+# ax_m.semilogx(f, db(np.abs(model(f))), "b", label="LPF")
+# ax_m.set_xlim(1e0, 1e3)
+# ax_m.set_ylabel("Magnitude [dB]")
+# ax_m.grid(visible=True, which="major")
+# ax_m.grid(visible=True, which="minor", linestyle=":")
+# ax_m.legend(loc=1)
+
+# # Phase
+# ax_p.semilogx(f, np.angle(model(f), deg=True), "b", label="LPF")
+# ax_p.set_xlim(1e0, 1e3)
+# ax_p.set_ylim(0, 90)
+# ax_p.set_xlabel("Frequency [Hz]")
+# ax_p.set_ylabel("Phase [deg]")
+# ax_p.grid(visible=True, which="major")
+# ax_p.grid(visible=True, which="minor", linestyle=":")
+# ax_p.legend(loc=1)
+
+# fig.savefig("without-pp@2x.png", dpi=600)