Adding docs and examples to github pages

.github/workflows/deploy-docs-versioned.yml

@@ -0,0 +1,60 @@
+name: Deploy versioned docs (mike)
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+permissions:
+  contents: write
+
+concurrency:
+  group: docs-deploy
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    container:
+      image: cubertgmbh/cuvis_pyil:3.5.3-ubuntu24.04
+    steps:
+      - name: Install build dependencies
+        run: apt-get update -y && apt-get install -y git doxygen graphviz
+
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          submodules: recursive
+
+      - name: Stage cuvis.h for Doxygen
+        run: |
+          mkdir -p docs/_api_sources
+          cp /usr/include/cuvis.h docs/_api_sources/cuvis.h
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+
+      - name: Sync docs deps
+        run: uv venv --system-site-packages && uv sync --extra docs
+
+      - name: Configure git for mike
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Build docs (strict)
+        run: uv run mkdocs build --strict
+
+      - name: Get version from tag
+        id: get_version
+        run: |
+          VERSION="${{ github.ref_name }}"
+          VERSION="${VERSION#v}"
+          echo "VERSION=${VERSION}" >> "$GITHUB_OUTPUT"
+
+      - name: Deploy docs with mike
+        run: |
+          uv run mike deploy --push --update-aliases ${{ steps.get_version.outputs.VERSION }} latest
+          uv run mike set-default --push latest

.github/workflows/deploy-docs.yml

@@ -1,55 +1,50 @@
-name: Deploy docs to GitHub Pages
+name: Deploy docs to GitHub Pages (nightly)
 
 on:
   push:
     branches: [main]
-    paths:
-      - docs/**
-      - tools/**
-      - scripts/cuvis_sdk_url.py
-      - mkdocs.yml
-      - pyproject.toml
-      - uv.lock
-      - .github/workflows/deploy-docs.yml
-  workflow_dispatch:
 
 permissions:
-  contents: read
-  pages: write
-  id-token: write
+  contents: write
 
 concurrency:
-  group: pages
+  group: docs-deploy
   cancel-in-progress: false
 
 jobs:
-  build:
+  deploy:
     runs-on: ubuntu-latest
+    container:
+      image: cubertgmbh/cuvis_pyil:3.5.3-ubuntu24.04
     steps:
+      - name: Install build dependencies
+        run: apt-get update -y && apt-get install -y git doxygen graphviz
+
       - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          submodules: recursive
+
+      - name: Stage cuvis.h for Doxygen
+        run: |
+          mkdir -p docs/_api_sources
+          cp /usr/include/cuvis.h docs/_api_sources/cuvis.h
 
       - name: Install uv
         uses: astral-sh/setup-uv@v4
         with:
           enable-cache: true
 
       - name: Sync docs deps
-        run: uv sync --extra docs
+        run: uv venv --system-site-packages && uv sync --extra docs
 
-      - name: Build site
-        run: uv run mkdocs build --strict
+      - name: Configure git for mike
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
 
-      - name: Upload Pages artifact
-        uses: actions/upload-pages-artifact@v3
-        with:
-          path: site
+      - name: Build docs (strict)
+        run: uv run mkdocs build --strict
 
-  deploy:
-    needs: build
-    runs-on: ubuntu-latest
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
-    steps:
-      - id: deployment
-        uses: actions/deploy-pages@v4
+      - name: Deploy dev (nightly) docs
+        run: uv run mike deploy --push dev

.github/workflows/docs-check.yml

@@ -0,0 +1,42 @@
+name: Docs build check
+
+on:
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: docs-check-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    container:
+      image: cubertgmbh/cuvis_pyil:3.5.3-ubuntu24.04
+    steps:
+      - name: Install build dependencies
+        run: apt-get update -y && apt-get install -y git doxygen graphviz
+
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          submodules: recursive
+
+      - name: Stage cuvis.h for Doxygen
+        run: |
+          mkdir -p docs/_api_sources
+          cp /usr/include/cuvis.h docs/_api_sources/cuvis.h
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+
+      - name: Sync docs deps
+        run: uv venv --system-site-packages && uv sync --extra docs
+
+      - name: Build site (strict)
+        run: uv run mkdocs build --strict

.gitignore

@@ -44,3 +44,11 @@ _assets/
 # uv-managed virtual envs and mkdocs build output.
 .venv/
 site/
+
+# mkdoxy-generated API reference pages (regenerated at each mkdocs build)
+docs/cuvis_c/
+docs/cuvis_cpp/
+
+# cuvis.h is sourced from the installed SDK at build time, not version-controlled.
+# Use scripts/fetch-cuvis-header.sh locally or the CI "Extract cuvis.h" step.
+docs/_api_sources/

CHANGELOG.md

@@ -2,4 +2,11 @@
 
 ## Unreleased
 
+- **Documentation site migrated into this repo** (from `cuvis.doc`) and published to GitHub Pages. Versioned with `mike`: pushing a `v*.*.*` tag publishes that version aliased to `latest` (`deploy-docs-versioned.yml`), and pushes to `main` publish a `dev` build (`deploy-docs.yml`). C and C++ API reference generated from the headers via `mkdoxy` (Doxygen XML), Python API reference via `mkdocstrings`, example pages generated from the Python notebooks, and an `llms.txt` / `llms-full.txt` index via `mkdocs-llmstxt`.
 - Rebranded the mkdocs site to follow Cubert CI. Switched the Material `palette` to `primary/accent: custom` and let `docs/stylesheets/extra.css` drive the palette directly across both Material schemes. Headings use Rajdhani via a Google Fonts `@import`; body and code stay on Roboto / Roboto Mono via Material's font loader. Existing `.sdk-installer` widget styles are preserved on top of the brand palette.
+- **CI: restored a strict docs build gate.** Added a `Docs build check` workflow (`.github/workflows/docs-check.yml`) that runs `mkdocs build --strict` on pull requests, plus a strict build step ahead of `mike deploy` in both the nightly and versioned deploy workflows, so dead links or missing generated pages fail CI instead of publishing a broken site.
+- **CI: serialized docs deploys.** Added a shared `concurrency: { group: docs-deploy, cancel-in-progress: false }` to both deploy workflows so a `main` push and a release-tag push cannot race each other's `git push` to `gh-pages`.
+- **Corrected the Examples overview** (`docs/examples/index.md`) to match the generated output: the example pages are Python-only, so the page no longer promises per-example C/C++ language tabs (the C/C++ sources live in the `examples/` submodules).
+- **Fixed dropped trailing prose in example-page generation.** `_parse_notebook` (`tools/example_pages.py`) now flushes the final section on leftover prose as well as code, so a notebook ending in a markdown cell keeps its closing text. Added `_parse_notebook` / `multilang_example` tests covering the trailing-markdown case, unknown example names, and missing notebooks.
+- **Fixed a Material theme feature typo** in `mkdocs.yml` (`content.code.annotation` → `content.code.annotate`) so code annotations render.
+- **llms.txt index:** added the Home page (`index.md`) to the `mkdocs-llmstxt` sections and clarified the description — the generated index covers the guide and Python API, with the full C/C++ reference browsable on the site (the generated mkdoxy pages are intentionally left out so the strict build has no plugin-order dependency).

docs/api/python.md

@@ -0,0 +1,67 @@
+# Python API Reference
+
+The Python wrapper mirrors the C and C++ API concepts. Signatures shown here
+are derived from static analysis of the source; see the C/C++ API reference
+for full parameter-level documentation.
+
+## General
+
+::: cuvis.General
+    options:
+      members: [init, shutdown, version, set_log_level]
+      show_source: false
+
+## SessionFile
+
+::: cuvis.SessionFile
+    options:
+      show_source: false
+
+## Measurement
+
+::: cuvis.Measurement
+    options:
+      show_source: false
+
+## ProcessingContext
+
+::: cuvis.ProcessingContext
+    options:
+      show_source: false
+
+## AcquisitionContext
+
+::: cuvis.AcquisitionContext
+    options:
+      show_source: false
+
+## Worker
+
+::: cuvis.Worker
+    options:
+      show_source: false
+
+## Viewer
+
+::: cuvis.Viewer
+    options:
+      show_source: false
+
+## Calibration
+
+::: cuvis.Calibration
+    options:
+      show_source: false
+
+## Export
+
+::: cuvis.Export
+    options:
+      show_source: false
+
+## Types & Enums
+
+::: cuvis.cuvis_types
+    options:
+      show_source: false
+      members_order: alphabetical

docs/examples/example_1_take_snapshot.md

@@ -0,0 +1 @@
+{{ multilang_example("Example_1_Take_Snapshot") }}

docs/examples/example_2_load_measurement.md

@@ -0,0 +1 @@
+{{ multilang_example("Example_2_Load_Measurement") }}

docs/examples/example_3_reprocess.md

@@ -0,0 +1 @@
+{{ multilang_example("Example_3_Reprocess") }}

docs/examples/example_4_exporters.md

@@ -0,0 +1 @@
+{{ multilang_example("Example_4_Exporters") }}

docs/examples/example_5_record_video.md

@@ -0,0 +1 @@
+{{ multilang_example("Example_5_Record_Video") }}

docs/examples/index.md

@@ -0,0 +1,22 @@
+# Examples
+
+The following examples demonstrate the core workflows of the Cuvis SDK.
+The pages below show the **Python** implementation, generated from the runnable
+Jupyter notebooks. C and C++ implementations of the same examples live in the
+SDK's `examples/` directory (`cuvis.c.examples` and `cuvis.cpp.examples`).
+
+!!! note "Prerequisites"
+    All examples require:
+
+    - A Cuvis SDK installation
+    - Camera settings files (provided with your camera and the SDK)
+    - For examples 2–5: a recorded measurement file (`.cu3s`) or the
+      [demo dataset](https://cloud.cubert-gmbh.de/s/SDKSampleData)
+
+| Example | Description |
+|---|---|
+| [1 – Take Snapshot](example_1_take_snapshot.md) | Connect to a camera and capture a single measurement |
+| [2 – Load Measurement](example_2_load_measurement.md) | Load a recorded `.cu3s` file and inspect its data |
+| [3 – Reprocess](example_3_reprocess.md) | Re-apply spectral processing to a stored measurement |
+| [4 – Exporters](example_4_exporters.md) | Export measurements to common file formats |
+| [5 – Record Video](example_5_record_video.md) | Continuously record a video stream of measurements |