diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index c791602..bb980d1 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -25,8 +25,7 @@ jobs: .config.yaml.template \ docker-compose.yml.template \ compose.all-in-one.yml \ - compose.local.override.yml \ - mkdocs.yml + compose.local.override.yml compose-validate: name: Compose Validate @@ -113,27 +112,6 @@ jobs: working-directory: dotty-pi-ext run: npm test - frontmatter-check: - name: Frontmatter Check - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v6 - - name: Verify YAML frontmatter in docs - run: | - fail=0 - for f in docs/*.md; do - # Skip symlinks — root-level files (README, ROADMAP, SETUP, etc.) - # are symlinked into docs/ for the mkdocs nav but are primarily - # consumed as plain GitHub markdown; YAML frontmatter would clutter - # their on-GitHub rendering. - [ -L "$f" ] && continue - if ! head -1 "$f" | grep -q '^---$'; then - echo "FAIL: $f missing YAML frontmatter" - fail=1 - fi - done - exit $fail - docs-links: name: Docs Link Check runs-on: ubuntu-latest @@ -153,7 +131,7 @@ jobs: notify-failure: name: Notify on Failure runs-on: ubuntu-latest - needs: [yaml-lint, compose-validate, config-parse, lint, python-tests, pi-ext-tests, frontmatter-check, docs-links] + needs: [yaml-lint, compose-validate, config-parse, lint, python-tests, pi-ext-tests, docs-links] if: failure() env: SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }} diff --git a/.github/workflows/docs-deploy.yml b/.github/workflows/docs-deploy.yml deleted file mode 100644 index 4006d84..0000000 --- a/.github/workflows/docs-deploy.yml +++ /dev/null @@ -1,110 +0,0 @@ -name: Deploy docs to GitHub Pages - -on: - # Pushes to main publish the 'dev' alias. - # Tag pushes (server-v*, fw-v*, v*) publish a versioned doc set and update - # the 'latest' alias. - # Path filters are deliberately omitted: mike deploys are cheap, and tag - # pushes don't always evaluate path filters reliably. - push: - branches: - - main - tags: - - "server-v*" - - "fw-v*" - - "v*" - workflow_dispatch: - inputs: - version: - description: "Version label to deploy (e.g. 0.1, 1.0). Leave blank to deploy as 'dev'." - required: false - default: "" - alias: - description: "Alias to update (e.g. latest). Leave blank for none." - required: false - default: "" - -permissions: - contents: write - -jobs: - deploy: - runs-on: ubuntu-latest - steps: - - name: Checkout - uses: actions/checkout@v6 - with: - fetch-depth: 0 - - - name: Configure git identity for mike - run: | - git config --global user.name "github-actions[bot]" - git config --global user.email "41898282+github-actions[bot]@users.noreply.github.com" - - - name: Fetch existing gh-pages branch (mike requires it) - run: | - git fetch origin gh-pages --depth=1 || echo "gh-pages branch not found yet; mike will create it on first deploy." - - - name: Set up Python - uses: actions/setup-python@v6 - with: - python-version: "3.12" - - - name: Install docs requirements - run: pip install -r docs/requirements.txt - - - name: Determine deploy mode - id: mode - env: - GITHUB_REF: ${{ github.ref }} - GITHUB_EVENT_NAME: ${{ github.event_name }} - INPUT_VERSION: ${{ github.event.inputs.version }} - INPUT_ALIAS: ${{ github.event.inputs.alias }} - run: | - set -euo pipefail - if [ "$GITHUB_EVENT_NAME" = "workflow_dispatch" ]; then - VERSION="${INPUT_VERSION:-dev}" - ALIAS="${INPUT_ALIAS:-}" - elif [[ "$GITHUB_REF" == refs/tags/* ]]; then - TAG="${GITHUB_REF#refs/tags/}" - # Strip server-v / fw-v / v prefix; keep MAJOR.MINOR for the doc version. - RAW="${TAG#server-v}" - RAW="${RAW#fw-v}" - RAW="${RAW#v}" - # Reduce 1.2.3 to 1.2 (per-tag docs are typically MAJOR.MINOR). - VERSION="$(echo "$RAW" | awk -F. '{ printf "%s.%s", $1, $2 }')" - ALIAS="latest" - elif [ "$GITHUB_REF" = "refs/heads/main" ]; then - VERSION="dev" - ALIAS="" - else - echo "Unsupported trigger: $GITHUB_REF"; exit 1 - fi - echo "version=$VERSION" >> "$GITHUB_OUTPUT" - echo "alias=$ALIAS" >> "$GITHUB_OUTPUT" - echo "Deploying version='$VERSION' alias='$ALIAS'" - - - name: Deploy with mike (tag -> versioned + latest) - if: steps.mode.outputs.alias == 'latest' - run: | - mike deploy --push --update-aliases \ - "${{ steps.mode.outputs.version }}" latest - - - name: Deploy with mike (main -> dev) - if: steps.mode.outputs.version == 'dev' && steps.mode.outputs.alias == '' - run: | - mike deploy --push "${{ steps.mode.outputs.version }}" - - - name: Deploy with mike (manual dispatch, custom) - if: github.event_name == 'workflow_dispatch' && steps.mode.outputs.version != 'dev' - run: | - if [ -n "${{ steps.mode.outputs.alias }}" ]; then - mike deploy --push --update-aliases \ - "${{ steps.mode.outputs.version }}" "${{ steps.mode.outputs.alias }}" - else - mike deploy --push "${{ steps.mode.outputs.version }}" - fi - - - name: Set default alias to 'latest' (idempotent) - if: steps.mode.outputs.alias == 'latest' - run: mike set-default --push latest diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index c56298b..cbabda3 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -22,9 +22,8 @@ repos: - id: end-of-file-fixer exclude: '^firmware/' - id: check-yaml - exclude: '^(mkdocs\.yml|\.github/workflows/.*\.yml|firmware/)' - # mkdocs.yml uses python tags (!!python/name:...) that PyYAML - # safe_load can't resolve; GHA workflows use the same. yamllint + exclude: '^(\.github/workflows/.*\.yml|firmware/)' + # GHA workflows use tags PyYAML safe_load can't resolve; yamllint # already lints them in CI. - id: check-json exclude: '^firmware/' diff --git a/CHANGELOG.md b/CHANGELOG.md index fa5d605..d165dbb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -87,7 +87,6 @@ First git-tagged public release. Covers all server + firmware work shipped to `m - **Wake-word options doc** (`docs/wake-word.md`) — current architecture, 21 prebuilt English wake words, three paths to "Hey Dotty" (Path A interim shipped, Path B microWakeWord roadmap, Path C wakenet9 custom). Sample collection guide. - **SBOM scaffold** (`scripts/generate-sbom.sh`, `docs/sbom.md`) — CycloneDX-ish component+license inventory. `make sbom`. - **Signed releases scaffold** (`docs/signed-releases.md`, `KEYS.txt`) — GPG signing walkthrough + CI integration snippet (commented-out signing step ready to enable). -- **Versioned docs via mike** (`mkdocs.yml`, `.github/workflows/docs-deploy.yml`, `docs/requirements.txt`, `docs/versioning.md`) — `/latest/`, `/v0.1/`, `/dev/` URL structure. ### Added — firmware (StackChan/dotty fork, 2026-04-25 sprint) - **Layer 1 privacy LEDs scaffold** — `PrivacyLeds` singleton drives right-ring index 6 (mic) + index 7 (camera). RAII `MicPeripheralGuard` + `CameraPeripheralGuard` tie LED state to peripheral enable codepath. New `self.robot.get_privacy_state` MCP tool. `set_led_multi` rejects indices 6/7. diff --git a/COMPATIBILITY.md b/COMPATIBILITY.md index c90ca77..84d56c5 100644 --- a/COMPATIBILITY.md +++ b/COMPATIBILITY.md @@ -7,7 +7,7 @@ server-side components: xiaozhi-esp32-server, the `dotty-pi` agent container, dotty-behaviour, and the `bridge.py` dashboard service. It describes what each component exposes, what counts as a breaking change, and how to upgrade safely. -For protocol wire formats see [protocols.md](https://brettkinny.github.io/dotty-stackchan/latest/protocols/). +For protocol wire formats see `docs/protocols.md`. ## Compatibility matrix @@ -92,14 +92,11 @@ Server and firmware are versioned independently: 3. Commit with message: `release: server-vX.Y.Z` (or `release: fw-vX.Y.Z`). 4. Create an annotated tag: `git tag -a server-vX.Y.Z -m "server-vX.Y.Z"` 5. Push the tag: `git push origin server-vX.Y.Z` -6. Deploy versioned docs (handled automatically by `.github/workflows/docs-deploy.yml` - on tag push; if you need to deploy manually, run - `mike deploy --push --update-aliases X.Y latest` from the repo root after - `pip install -r docs/requirements.txt`). See - [`versioning.md`](https://brettkinny.github.io/dotty-stackchan/latest/versioning/) for the full URL/alias model. - -GitHub Actions handles image builds, artifact publishing, and versioned doc -deploys from the tag. + +The docs live as plain markdown under `docs/` and render on GitHub directly — +there is no separate docs-site build to deploy. + +GitHub Actions handles image builds and artifact publishing from the tag. ### Compatibility matrix updates diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6a2c9b1..e86a9bf 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -74,20 +74,6 @@ deployments must use a placeholder: Port numbers (`8000`, `8003`, `8080`, `18789`, `42617`) are product-generic and do not need placeholders. -## Documentation versioning - -The docs site is published per-version using -[`mike`](https://github.com/jimporter/mike). Pushes to `main` update the -`/dev/` alias automatically; tag pushes (`server-vX.Y.Z`, `fw-vX.Y.Z`) publish -a versioned tree at `/vX.Y/` and bump the `/latest/` alias. See -[`versioning.md`](https://brettkinny.github.io/dotty-stackchan/latest/versioning/) for the URL structure, version -dropdown behavior, and maintainer commands (`mike deploy ... --push`, -`mike list`, `mike delete`). - -When you add or rename a doc, prefer edits that work cleanly across versions -(don't break links from older versions to ones that still exist). If a doc is -only relevant for a future version, note that in the PR description. - ## AI-assisted contributions This project is openly AI-assisted, and your contributions can be too — using a diff --git a/docs/assets/dotty-hero.svg b/docs/assets/dotty-hero.svg deleted file mode 100644 index 87f988a..0000000 --- a/docs/assets/dotty-hero.svg +++ /dev/null @@ -1,39 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/requirements.txt b/docs/requirements.txt deleted file mode 100644 index 6c5c53b..0000000 --- a/docs/requirements.txt +++ /dev/null @@ -1,3 +0,0 @@ -mkdocs-material>=9.5 -mike>=2.1 -pymdown-extensions>=10 diff --git a/docs/style.md b/docs/style.md index 276e2d6..a82cee0 100644 --- a/docs/style.md +++ b/docs/style.md @@ -27,7 +27,8 @@ description: One-line summary of what this page covers. --- ``` -MkDocs Material uses these for the HTML `` and search index. +It's a concise, machine-readable summary of the page — handy for tooling and +for readers skimming the raw file. ## Headings @@ -40,7 +41,7 @@ MkDocs Material uses these for the HTML `<title>` and search index. 1. Create the file in `docs/cookbook/` (e.g. `docs/cookbook/do-the-thing.md`). 2. Add frontmatter (`title` + `description`). -3. Add a nav entry in `mkdocs.yml` under the `Cookbook:` section. +3. Link it from `docs/README.md` so it's discoverable. 4. Keep it short — one task, one page. Link to reference docs for background. ## Decay annotations @@ -87,4 +88,4 @@ IPs, hostnames, or API keys. ## Keep it short If a page is getting long, split it. One concept per page, one task per -cookbook entry. The nav is cheap — use it. +cookbook entry — then link the pieces together. diff --git a/docs/versioning.md b/docs/versioning.md deleted file mode 100644 index 4e81eec..0000000 --- a/docs/versioning.md +++ /dev/null @@ -1,113 +0,0 @@ ---- -title: Documentation Versioning -description: How the Dotty docs site is versioned, what /latest/ vs /dev/ vs /vX.Y/ mean, and how maintainers cut a versioned doc release. ---- - -# Documentation Versioning - -## TL;DR - -| URL | What it shows | When to read it | -|---|---|---| -| `/latest/` | Docs for the most recent tagged release | You are running a stable, tagged build | -| `/vX.Y/` | Docs frozen at a specific minor version (e.g. `/v0.1/`) | You are pinned to that firmware/server version | -| `/dev/` | Docs from the tip of `main` | You build from source or follow `main` | - -A version dropdown sits next to the site title and switches between any -of the published versions. The default landing page is `/latest/`. - -## Why versioned docs? - -The firmware and the server can lag each other. A user on `fw-v0.1.0` should -not be reading instructions written against `fw-v1.0.0` -- the MCP tool surface -or the WebSocket frame shape may have shifted. See -[COMPATIBILITY.md](COMPATIBILITY.md) for the full breaking-change policy. - -## Version policy - -Versions follow SemVer. Tag namespaces are split between server and firmware -(see [COMPATIBILITY.md](COMPATIBILITY.md#tag-namespaces)): - -- **Server** -- `server-vX.Y.Z` (bridge, custom providers, docker compose). -- **Firmware** -- `fw-vX.Y.Z` (ESP32-S3 StackChan firmware). - -The docs site publishes one version label per **MAJOR.MINOR** (e.g. `0.1`, -`1.0`, `1.1`). Patch releases overwrite the minor's published version -- -so `server-v0.1.0`, `server-v0.1.1`, and `server-v0.1.2` all live at -`/v0.1/`, with the most recent patch winning. - -`latest` always points to the most recently tagged version. - -## Reading the version dropdown - -The dropdown next to the Dotty title shows every published version. Pick one -and the whole site reloads in that version's tree. The version label appears -at the top of every page so it is obvious which version you are reading. - -If a page only exists in newer versions, the older version's site shows a 404 -for that page. That is expected -- the older version's docs reflect what was -true at that release. - -## Maintainer notes - -The docs site is built with [MkDocs Material](https://squidfunk.github.io/mkdocs-material/) -and versioned with [`mike`](https://github.com/jimporter/mike). Versions live -on the `gh-pages` branch under per-version folders. - -### Cutting a versioned doc release - -Versioned docs deploy automatically on tag push -- the -`docs-deploy.yml` workflow extracts MAJOR.MINOR from the tag, runs -`mike deploy --push --update-aliases <version> latest`, and updates the -`latest` alias. - -Pushes to `main` deploy as the `dev` alias, leaving `latest` untouched. - -### Manual deploy from a workstation - -If you need to rebuild a version locally (e.g. a doc-only fix on an older -release): - -```bash -# From the repo root -pip install -r docs/requirements.txt - -# Fetch the gh-pages branch so mike has somewhere to commit. -git fetch origin gh-pages - -# Deploy version 0.1 and update the 'latest' alias to point at it. -mike deploy --push --update-aliases 0.1 latest - -# Or deploy a 'dev' build without touching 'latest'. -mike deploy --push dev - -# Set the default version (the one users land on at the site root). -mike set-default --push latest -``` - -### Listing and removing versions - -```bash -# List published versions -mike list - -# Delete a stale version -mike delete --push 0.0 -``` - -### Bootstrapping the site for the first time - -`mike` expects to commit onto an existing `gh-pages` branch. If the repo has -never deployed docs, the first `mike deploy --push` call creates the branch. -If the repo previously used `mkdocs gh-deploy --force` (no versioning), the -first `mike deploy` overwrites the existing flat layout with a versioned one --- existing URLs at the site root will break, and visitors should be -redirected to `/latest/`. - -## See also - -- [COMPATIBILITY.md](COMPATIBILITY.md) -- the breaking-change policy and - release process. -- [CONTRIBUTING.md](CONTRIBUTING.md) -- how to contribute documentation - alongside code. -- [`mike` upstream](https://github.com/jimporter/mike) -- the underlying tool. diff --git a/mkdocs.yml b/mkdocs.yml deleted file mode 100644 index ad7776b..0000000 --- a/mkdocs.yml +++ /dev/null @@ -1,104 +0,0 @@ -site_name: Dotty -site_description: >- - Your self-hosted StackChan robot assistant. - Open-source firmware, local ASR/TTS, pluggable LLM brain — no cloud required. -site_url: https://brettkinny.github.io/dotty-stackchan -repo_url: https://github.com/BrettKinny/dotty-stackchan -repo_name: BrettKinny/dotty-stackchan - -theme: - name: material - logo: assets/dotty-hero.svg - favicon: assets/dotty-hero.svg - palette: - - media: "(prefers-color-scheme: light)" - scheme: default - primary: indigo - accent: indigo - toggle: - icon: material/brightness-7 - name: Switch to dark mode - - media: "(prefers-color-scheme: dark)" - scheme: slate - primary: indigo - accent: indigo - toggle: - icon: material/brightness-4 - name: Switch to light mode - features: - - navigation.tabs - - navigation.sections - - navigation.top - - search.suggest - - search.highlight - - content.code.copy - -plugins: - - search - -nav: - - Home: README.md - - Getting Started: SETUP.md - - Quickstart: quickstart.md - - Architecture: architecture.md - - Hardware: hardware.md - - Voice Pipeline: voice-pipeline.md - - Voice Mode Entry: voice-mode-entry.md - - Voice Catalog: voice-catalog.md - - Wake Word: wake-word.md - - Modes: modes.md - - Proactive Greetings: proactive-greetings.md - - Brain: brain.md - - Protocols: protocols.md - - OTA Verification: ota-verification.md - - Kid Mode: kid-mode.md - - LLM Backends: llm-backends.md - - Observability: observability.md - - Cookbook: - - Change Persona: cookbook/change-persona.md - - Swap Voice: cookbook/swap-voice.md - - Run Fully Local: cookbook/run-fully-local.md - - Add Emoji: cookbook/add-emoji.md - - Disable Kid Mode: cookbook/disable-kid-mode.md - - Concurrent Models (llama-swap): cookbook/llama-swap-concurrent-models.md - - Reference: - - Emoji Mapping: emoji-mapping.md - - Interaction Map: interaction-map.md - - Latent Capabilities: latent-capabilities.md - - References: references.md - - Troubleshooting: troubleshooting.md - - FAQ: faq.md - - About: about.md - - AI Transparency: AI_TRANSPARENCY.md - - Roadmap: ROADMAP.md - - Contributing: CONTRIBUTING.md - - Style Guide: style.md - - Security: SECURITY.md - - Compatibility: COMPATIBILITY.md - - SBOM: sbom.md - - Reproducible Builds: reproducible-builds.md - - Versioning: versioning.md - - Changelog: CHANGELOG.md - -extra: - version: - provider: mike - default: latest - -markdown_extensions: - - toc: - permalink: true - - tables - - admonition - - pymdownx.details - - pymdownx.highlight: - anchor_linenums: true - - pymdownx.superfences: - custom_fences: - - name: mermaid - class: mermaid - format: !!python/name:pymdownx.superfences.fence_code_format - - pymdownx.tabbed: - alternate_style: true - - attr_list - - md_in_html