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,31 +1,38 @@
+---
+layout: home
+title: Open Echo
+nav_exclude: true
+---
+
+
 <img alt="Open Echo Cover" src="documentation/images/open_echo_logo.svg">
 
 ## Universal Open-Source SONAR Controller and Development Stack
 
 An ongoing open-source hardware and software project for building sonar systems for testing, boating, bathymetry, and research.  
-The most commonly used hardware is the [TUSS4470 Arduino Shield](TUSS4470_shield_002/), which stacks on top of an Arduino Uno to drive the TUSS4470 ultrasonic driver.  
-The board can run the [RAW Data Firmware](TUSS4470_shield_002/getting_started_TUSS4470_firmware.md) to operate a wide variety of ultrasonic transducers, covering frequencies from 40 kHz up to 1000 kHz in different media such as air or water.  
+The most commonly used hardware is the [TUSS4470 Arduino Shield](documentation/getting_started/TUSS4470_hardware.md), which stacks on top of an Arduino Uno to drive the TUSS4470 ultrasonic driver.  
+The board can run the [RAW Data Firmware](documentation/getting_started/desktop_interface.md) to operate a wide variety of ultrasonic transducers, covering frequencies from 40 kHz up to 1000 kHz in different media such as air or water.  
 
-The [NMEA Output Firmware](TUSS4470_shield_002/arduino/NMEA_DBT_OUT/NMEA_DBT_OUT.ino) can read depth data from commercially available in-water ultrasonic transducers (e.g., on boats) and output NMEA0183-compatible data to a computer or a UART-connected device such as a Pixhawk or other controllers.  
+The [NMEA Output Firmware](https://github.com/neumi/open_echo/tree/main/TUSS4470_shield_002/arduino/NMEA_DBT_OUT/NMEA_DBT_OUT.ino) can read depth data from commercially available in-water ultrasonic transducers (e.g., on boats) and output NMEA0183-compatible data to a computer or a UART-connected device such as a Pixhawk or other controllers.  
 
 Open Echo has been tested on multiple ultrasonic transducers and is compatible with all of them—from car parking sensors to Lowrance Tripleshot side-scan transducers.  
 
-The [Python Interface Software](TUSS4470_shield_002/getting_started_interface.md) connects to Open Echo boards running the [RAW Data Firmware](TUSS4470_shield_002/getting_started_TUSS4470_firmware.md). It can display raw echo data, change configurations, output a TCP depth data stream, and more.  
+The [Python Interface Software](documentation/getting_started/desktop_interface.md) connects to Open Echo boards running the [RAW Data Firmware](documentation/getting_started/TUSS4470_firmware.md). It can display raw echo data, change configurations, output a TCP depth data stream, and more.  
 
-Check the [Getting Started Guide](TUSS4470_shield_002/README.md)!  
+Check the [Getting Started Guide](documentation/getting_started/index.md)!  
 
 If something is unclear or you find a bug, please open an issue.  
 
 
 Raw Data Waterfall chart in the Python Desktop software:  
-<img alt="Open Echo Interface Software" src="/documentation/images/echo_software_screenshot.jpg">
+<img alt="Open Echo Interface Software" src="documentation/images/echo_software_screenshot.jpg">
 
 
 ## Getting the Hardware
 
-If you need the hardware, you can order it using the [Hardware Files](TUSS4470_shield_002/TUSS4470_shield_hardware/TUSS4470_shield) from a board + SMT house ([JLC recommended](https://jlcpcb.com/?from=Neumi)).
+If you need the hardware, you can order it using the [Hardware Files](https://github.com/neumi/open_echo/tree/main/TUSS4470_shield_002/TUSS4470_shield_hardware/TUSS4470_shield) from a board + SMT house ([JLC recommended](https://jlcpcb.com/?from=Neumi)).
 
-They can also be bought as a complete and tested set direclty from Elecrow: https://www.elecrow.com/open-echo-tuss4470-development-shield.html
+They can also be bought as a complete and tested set directly from Elecrow: https://www.elecrow.com/open-echo-tuss4470-development-shield.html
 
 If they’re out of stock, or if you’d prefer to order them within Germany to reduce shipping costs, please send me an email at: openechoes@gmail.com
 
@@ -36,12 +43,12 @@ All profits go directly toward supporting and advancing the Open Echo project!
 [TUSS4470 Arduino Shield](TUSS4470_shield_002/):  
 <img alt="PCB overview TUSS4470" src="/documentation/images/TUSS4470_shield002.jpg">
 
-### This project is currently in development. The [TUSS4470 Development Shield](TUSS4470_shield_002/) is ready for external use!  
+### This project is currently in development. The [TUSS4470 Development Shield](documentation/getting_started/TUSS4470_hardware.md) is ready for external use!  
 Development is ongoing! Check the documentation and Discord channel for the latest updates.  
 
 Want to stay updated or participate? Join the [Discord](https://discord.com/invite/rerCyqAcrw)!  
 
-Check the [Getting Started Guide](TUSS4470_shield_002/README.md).  
+Check the [Getting Started Guide](documentation/getting_started/).  
 
 ## Vision
 An accessible Open Source SONAR stack for development, research and real use: