Refactor python code, add publish workflows, add docs website

.githooks/pre-commit

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+echo "[pre-commit] Running ruff (fix), pytest, and mypy..."
+
+# Only run if Python files changed; otherwise skip quickly
+changed_py=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.py$' || true)
+if [[ -z "$changed_py" ]]; then
+  echo "[pre-commit] No Python changes detected. Skipping checks."
+  exit 0
+fi
+
+if ! command -v uv >/dev/null 2>&1; then
+  echo "[pre-commit] 'uv' not found. Install from https://github.com/astral-sh/uv"
+  exit 1
+fi
+
+# Lint and auto-fix Python code
+echo "[pre-commit] Ruff: check & fix"
+uvx ruff check --fix
+
+# Re-stage any auto-fixed files so the commit includes updates
+git add -A
+
+# Run tests
+echo "[pre-commit] Pytest"
+uv run pytest -q python/
+
+# Type checking
+echo "[pre-commit] Mypy"
+uv run mypy
+
+echo "[pre-commit] All checks passed. Proceeding with commit."
+exit 0

.github/workflows/docs.yml

@@ -0,0 +1,45 @@
+name: Publish Docs to GitHub Pages
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'documentation/**'
+      - '_config.yml'
+      - 'Gemfile'
+      - 'README.md'
+
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.4' # Not needed with a .ruby-version, .tool-versions or mise.toml
+          bundler-cache: true # runs 'bundle install' and caches installed gems automatically
+      - name: Build with Jekyll
+        run: bundle exec jekyll build
+        env:
+          JEKYLL_ENV: production
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+  deploy:
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}

.github/workflows/pypi-publish.yml

@@ -0,0 +1,37 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  test-lint-typecheck:
+    uses: ./.github/workflows/python-ci.yml
+  build-and-publish:
+    needs: test-lint-typecheck
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      id-token: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Setup uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: Build package (sdist and wheel)
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_TOKEN }}
+          # Uncomment to be verbose or skip existing versions
+          # verbose: true
+          # skip-existing: true

.github/workflows/python-ci.yml

@@ -0,0 +1,41 @@
+name: Python CI
+
+on:
+  workflow_call:
+  push:
+    branches: ["**"]
+    paths:
+      - '**/*.py'
+      - 'pyproject.toml'
+  pull_request:
+    branches: ["**"]
+    paths:
+      - '**/*.py'
+      - 'pyproject.toml'
+
+jobs:
+  test-lint-typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Setup uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: Sync dependencies (including dev)
+        run: uv sync --all-extras --dev
+
+      - name: Run tests (pytest)
+        run: uv run pytest
+
+      - name: Lint (ruff)
+        run: uvx ruff check
+
+      - name: Type check (mypy)
+        run: uv run mypy

.gitignore

@@ -1,3 +1,8 @@
 __pycache__/
 .*
 !.gitignore
+!.githooks
+!.github
+__about__.py
+_site
+*.lock

Gemfile

@@ -0,0 +1,33 @@
+source "https://rubygems.org"
+# Hello! This is where you manage which Jekyll version is used to run.
+# When you want to use a different version, change it below, save the
+# file and run `bundle install`. Run Jekyll with `bundle exec`, like so:
+#
+#     bundle exec jekyll serve
+#
+# This will help ensure the proper Jekyll version is running.
+# Happy Jekylling!
+gem "jekyll", "~> 4.4.1"
+# This is the default theme for new Jekyll sites. You may change this to anything you like.
+gem "just-the-docs"
+# If you have any plugins, put them here!
+group :jekyll_plugins do
+  gem "jekyll-feed", "~> 0.12"
+  gem "jekyll-readme-index"
+  gem "jekyll-gfm-admonitions"
+  gem "jekyll-relative-links"
+end
+
+# Windows and JRuby does not include zoneinfo files, so bundle the tzinfo-data gem
+# and associated library.
+platforms :mingw, :x64_mingw, :mswin, :jruby do
+  gem "tzinfo", ">= 1", "< 3"
+  gem "tzinfo-data"
+end
+
+# Performance-booster for watching directories on Windows
+gem "wdm", "~> 0.1", :platforms => [:mingw, :x64_mingw, :mswin]
+
+# Lock `http_parser.rb` gem to `v0.6.x` on JRuby builds since newer versions of the gem
+# do not have a Java counterpart.
+gem "http_parser.rb", "~> 0.6.0", :platforms => [:jruby]

README.md

@@ -1,3 +1,10 @@
+---
+layout: home
+title: Open Echo
+nav_exclude: true
+---
+
+
 <div align="center">
   <img align="right" style="width:300px" alt="Open Echo Cover" src="documentation/images/open_echo_logo.svg">
 </div>
@@ -6,7 +13,7 @@
 
 An ongoing open-source hardware and software project for building sonar systems for testing, boating, bathymetry, and research.
 
-[Discord](https://discord.com/invite/rerCyqAcrw) | [Getting Started Guide](TUSS4470_shield_002/README.md) | [Hardware Files](TUSS4470_shield_002/TUSS4470_shield_hardware/TUSS4470_shield)
+[Discord](https://discord.com/invite/rerCyqAcrw) | [Getting Started Guide](documentation/getting_started/index.md) | [Hardware Files](https://github.com/neumi/open_echo/tree/main/TUSS4470_shield_002/TUSS4470_shield_hardware/TUSS4470_shield)
 
 ## Overview
 
@@ -17,14 +24,14 @@ Use cases range from reverse-engineering car parking sensors and reading depth d
 ### Key Features
 
 * **Universal Transducer Support:** Works with commercial and DIY transducers in water and air.
-* **Flexible Firmware:** Run the [RAW Data Firmware](TUSS4470_shield_002/getting_started_TUSS4470_firmware.md) to process echoes yourself, or the [NMEA Output Firmware](TUSS4470_shield_002/arduino/NMEA_DBT_OUT/NMEA_DBT_OUT.ino) for NMEA0183 DBT compatibility (sends depth data directly to PCs, Pixhawk, or marine controllers).
-* **Python Interface:** The [desktop software](TUSS4470_shield_002/getting_started_interface.md) provides live raw data visualization and TCP data streaming.
+* **Flexible Firmware:** Run the [RAW Data Firmware](documentation/getting_started/TUSS4470_firmware.md) to process echoes yourself, or the [NMEA Output Firmware](https://github.com/neumi/open_echo/tree/main/TUSS4470_shield_002/arduino/NMEA_DBT_OUT/NMEA_DBT_OUT.ino) for NMEA0183 DBT compatibility (sends depth data directly to PCs, Pixhawk, or marine controllers).
+* **Python Interface:** The [desktop software](documentation/getting_started/desktop_interface.md) provides live raw data visualization and TCP data streaming.
 * **Tested Range:** Confirmed depth tracking of >50 m in water.
 * **Network Ready:** Includes a PicoW implementation (software only, the shield itself is Arduino UNO R3 compatible) that transfers RAW data over UDP directly to the Python interface.
 
 ## Hardware & Getting Started
 
-The primary development platform is the [TUSS4470 Arduino Shield](TUSS4470_shield_002/). It stacks directly on top of an Arduino Uno to drive the TUSS4470 ultrasonic driver.
+The primary development platform is the [TUSS4470 Arduino Shield](documentation/getting_started/TUSS4470_hardware.md). It stacks directly on top of an Arduino Uno to drive the TUSS4470 ultrasonic driver.
 
 **Upcoming Board:** A new development version is in the works and will hopefully be released in the coming weeks. It features an on-board boost converter and slightly improved signal routing.
 
@@ -34,14 +41,14 @@ The primary development platform is the [TUSS4470 Arduino Shield](TUSS4470_shiel
 ### Getting the Hardware
 
 1. **Elecrow (Pre-Built):** Buy a fully assembled and tested board here: [Elecrow Open Echo TUSS4470](https://www.elecrow.com/open-echo-tuss4470-development-shield.html)
-2. **Build Your Own:** Order the [Hardware Files](TUSS4470_shield_002/TUSS4470_shield_hardware/TUSS4470_shield) from your preferred PCB manufacturer (JLCPCB recommended).
+2. **Build Your Own:** Order the [Hardware Files](https://github.com/neumi/open_echo/tree/main/TUSS4470_shield_002/TUSS4470_shield_hardware/TUSS4470_shield) from your preferred PCB manufacturer (JLCPCB recommended).
 3. **Directly from me (Germany/EU):** If Elecrow is out of stock or you want to reduce shipping costs within Germany, email me at: `openechoes@gmail.com`.
 
 > **Note:** All profits go directly toward supporting the project. Please understand that I can only provide support if you order the boards directly from me or Elecrow.
 
 ## Open Echo Interface Software
 
-The [Python Interface Software](TUSS4470_shield_002/echo_interface.py) connects to boards running the RAW Data Firmware. It serves as a simple backend to view live echograms and output TCP depth data streams. (Configuration tweaking directly from the UI will be added later).
+The [Python Interface Software](documentation/getting_started/desktop_interface.md) connects to boards running the RAW Data Firmware. It serves as a simple backend to view live echograms and output TCP depth data streams. (Configuration tweaking directly from the UI will be added later).
 
 Live echogram in water (6x speed):  
 <img alt="Software running with live echo data" src="documentation/images/echogram_fast.gif" width="600">