feat(docs): add MkDocs site and GitHub Pages deploy workflow

.github/workflows/ci-cd.yml

@@ -27,7 +27,7 @@ jobs:
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
-        pip install -e .[plot,pybamm,openmdao,dev]
+        pip install -e .[plot,openmdao,dev]
 
     - name: Run tests
       run: |

.github/workflows/docs.yml

@@ -0,0 +1,34 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+      - '.github/workflows/docs.yml'
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-24.04
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install Dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .[docs]
+
+      - name: Deploy to GitHub Pages
+        run: |
+          mkdocs gh-deploy --force

.gitignore

@@ -10,10 +10,11 @@ venv/
 # output folders
 *_out/
 build/
+site/
 .antigravitycli/
 scratch/
 
 # Test and Coverage
 .coverage
 .pytest_cache/
-htmlcov/
+htmlcov/

README.md

@@ -12,9 +12,6 @@ PyThrust is an open-source framework for electric propulsion system analysis, co
 | **3. Propeller Aerodynamic Coefficients** | **4. Hover Efficiency Heatmap** |
 | ![Propeller Aerodynamic Coefficients](https://raw.githubusercontent.com/Setuav/PyThrust/main/docs/images/propeller_coefficients.png) | ![Hover Efficiency Heatmap](https://raw.githubusercontent.com/Setuav/PyThrust/main/docs/images/efficiency_heatmap.png) |
 
-### 5. PyBaMM Electrochemical Battery Simulation (Dynamic Load)
-![PyBaMM Electrochemical Battery Simulation](https://raw.githubusercontent.com/Setuav/PyThrust/main/docs/images/pybamm_mission_results.png)
-
 ## Documentation
 
 Please see the [docs/](https://github.com/Setuav/PyThrust/tree/main/docs) folder for design specifications, core mathematical model descriptions, and database details.
@@ -25,4 +22,4 @@ PyThrust is licensed under the Apache License, Version 2.0 (the "License"). See
 
 ## Copyright
 
-Copyright (c) 2026 Setuav. All rights reserved.
+Copyright (c) 2026 Setuav. All rights reserved.

docs/api_reference.md

@@ -0,0 +1,132 @@
+# API Reference
+
+This page summarizes the main public classes and helpers. For implementation details, see the source modules under `pythrust/`.
+
+## Propulsion Models
+
+`MotorSpec` defines brushless motor electrical parameters:
+
+| Field | Unit | Description |
+|---|---:|---|
+| `kv_rpm_per_v` | RPM/V | Motor speed constant |
+| `resistance_ohm` | ohm | Winding resistance |
+| `no_load_current_a` | A | Datasheet no-load current |
+| `current_max_a` | A | Maximum continuous or configured current limit |
+| `torque_constant_kv_ratio` | - | Optional second-order motor model ratio |
+| `magnetic_lag_tau` | s | Optional magnetic lag time constant |
+| `iron_loss_exponent` | - | Optional no-load current speed scaling exponent |
+
+Use `get_no_load_current(rpm)` and `get_winding_resistance(current_a)` when evaluating speed-dependent or current-dependent motor behavior.
+
+## Battery, System, and Propeller Specs
+
+| Class | Purpose |
+|---|---|
+| `BatterySpec` | Pack voltage and discharge efficiency |
+| `SystemSpec` | Lumped electrical resistance for battery, ESC, wires, and connectors |
+| `PropellerSpec` | Propeller geometry passed to the solver |
+| `OperatingPoint` | Solved RPM, thrust, torque, power, current, voltage, efficiency, and feasibility state |
+
+## Propulsion Solver
+
+`PropulsionSolver` solves the coupled electrical and aerodynamic equilibrium for a single operating condition:
+
+```python
+point = solver.solve_operating_point(
+    motor=motor,
+    battery=battery,
+    system=system,
+    propeller=propeller,
+    prop_entry=prop_entry,
+    rho=1.225,
+    airspeed_mps=15.0,
+    throttle=0.7,
+)
+```
+
+`SolverConfig` controls numerical behavior:
+
+| Field | Default | Description |
+|---|---:|---|
+| `rpm_min` | `100.0` | Lower RPM bound |
+| `rpm_max_margin` | `1.1` | Safety factor on estimated maximum RPM |
+| `eps_rpm` | `1e-8` | RPM convergence tolerance |
+| `eps_v` | `1e-8` | Voltage residual tolerance |
+| `max_iter` | `100` | Maximum root-finder iterations |
+
+## Propeller Database
+
+`PropellerDatabase` loads JSON metadata and CSV performance tables:
+
+```python
+from pathlib import Path
+from pythrust.propellers import PropellerDatabase
+
+db = PropellerDatabase()
+db.load(Path("data/propellers/apc_202602"), strict=False)
+entry = db.get("APC_13x6.5E")
+ct, cp = entry.get_coefficients(rpm=5000.0, advance_ratio=0.4)
+```
+
+Main helpers:
+
+| Method | Description |
+|---|---|
+| `load(data_dir, strict=False)` | Load every propeller JSON file in a directory |
+| `load_entry(json_path, data_dir=None, strict=False)` | Load one propeller entry |
+| `list_propellers()` | Return sorted propeller IDs |
+| `get(prop_id)` | Return a `PropellerEntry` by ID |
+| `find_by_size(diameter_in, pitch_in, blade_count=2, tolerance=0.5)` | Find the closest size match |
+| `get_interpolated_coefficients(...)` | Fetch `Ct` and `Cp` through a size lookup |
+
+## Motor Database
+
+`MotorDatabase` loads brushless motor JSON files and converts catalog entries into solver specs:
+
+```python
+from pathlib import Path
+from pythrust.motors import MotorDatabase
+
+db = MotorDatabase()
+db.load(Path("data/motors"))
+motor_entry = db.get("SunnySky_X2826_KV550")
+motor = motor_entry.to_spec()
+```
+
+Main helpers:
+
+| Method | Description |
+|---|---|
+| `load(data_dir)` | Recursively load motor JSON files |
+| `load_entry(json_path)` | Load one motor JSON file |
+| `list_motors()` | Return sorted motor IDs |
+| `get(motor_id)` | Return a `MotorEntry` by ID |
+| `search(...)` | Filter by Kv, current, and weight constraints |
+
+## Calibration
+
+`PropulsionCalibrator` fits `SystemSpec.resistance_ohm` against manufacturer or thrust-stand data:
+
+```python
+from pythrust.propulsion import PropulsionCalibrator
+
+calibrator = PropulsionCalibrator(system_bounds=(0.0, 1.0))
+points = calibrator.load_csv("table.csv")
+result = calibrator.calibrate(
+    points,
+    motor,
+    battery,
+    system,
+    propeller,
+    prop_entry,
+)
+system = result.to_system_spec()
+```
+
+`CalibrationResult` reports fitted resistance, thrust/current RMSE values, thrust `R^2`, convergence status, and quality warnings.
+
+## OpenMDAO
+
+`pythrust.openmdao.PropulsionComponent` wraps `PropulsionSolver` as an `ExplicitComponent` for optimization models.
+
+Inputs include motor parameters, battery voltage, system resistance, propeller diameter, throttle, density, and airspeed. Outputs include RPM, thrust, torque, battery current, battery power, motor current, motor voltage, and feasibility.

docs/databases.md

@@ -38,7 +38,7 @@ rpm,speed_mps,advance_ratio,efficiency,thrust_coeff,power_coeff,power_w,torque_n
 
 ## 2) Brushless Motor Database (`data/motors/`)
 
-The motor database is a directory of individual JSON files representing fırçasız (brushless) motors.
+The motor database is a directory of individual JSON files representing brushless motors.
 
 ### Motor Spec format (`*.json`)
 ```json

docs/development.md

@@ -0,0 +1,60 @@
+# Development & Testing
+
+This guide covers local development, tests, examples, and documentation publishing.
+
+## Local Environment
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+pip install -e .[plot,openmdao,dev,docs]
+```
+
+## Run Tests
+
+```bash
+pytest
+```
+
+The CI workflow runs the test suite on Python 3.10, 3.11, and 3.12.
+
+## Run Example Workflows
+
+```bash
+PYTHONPATH=. python examples/select_motor.py
+PYTHONPATH=. python examples/calibrate_from_datasheet.py
+PYTHONPATH=. python examples/optimize_and_plot_propulsion.py
+```
+
+See [Examples](examples.md) for a user-facing walkthrough of each script.
+
+Generated plots are written under `docs/images/` and are used by the documentation site.
+
+## Documentation Site
+
+PyThrust uses MkDocs Material for a clean, searchable static documentation site.
+
+Serve locally:
+
+```bash
+mkdocs serve
+```
+
+Build static HTML:
+
+```bash
+mkdocs build --strict
+```
+
+Deploy manually to GitHub Pages:
+
+```bash
+mkdocs gh-deploy --force
+```
+
+## GitHub Pages Publishing
+
+The `Deploy Docs` workflow publishes the MkDocs site when documentation files, `mkdocs.yml`, or the workflow itself change on `main`.
+
+In the GitHub repository settings, configure Pages to publish from the `gh-pages` branch after the first successful deploy.