Skip to content

Commit 62860e2

Browse files
birkholz-cubertnghorbani
birkholz-cubert
and
nghorbani
authored
Adding docs and examples to github pages (#88)
* Added documentation for examples to mkdocs - Add `.github/workflows/deploy-docs.yml`: two-job pipeline (build with `uv run mkdocs build --strict` → upload Pages artifact → deploy via `actions/deploy-pages@v4`). Triggers on push to main with path filters plus `workflow_dispatch`. - Add `site_url: https://cubert-hyperspectral.github.io/cuvis.sdk/` to `mkdocs.yml` so Material emits the correct sitemap and absolute OG/canonical links. To go live: Settings → Pages → Source → "GitHub Actions", then push any docs change or run the workflow manually. * adding python examples to doc (for now python only) * only docs deploy for master branch and one for version tags * correctly normalizing markdown lists * removing unneeded file * docs: harden docs CI and fix example-page generation - Add a strict mkdocs build check on PRs and before each mike deploy so broken links or missing generated pages fail CI instead of publishing a broken site. - Serialize nightly and versioned deploys with a shared concurrency group to avoid racing pushes to gh-pages. - Correct the Examples overview: the generated example pages are Python-only. - Keep trailing prose in notebook-derived pages (_parse_notebook now flushes a final markdown-only section) and add tests covering it. - Fix mkdocs feature flag typo: content.code.annotation -> content.code.annotate. * docs: include Home page in llms.txt index and clarify scope Add index.md to the mkdocs-llmstxt sections so the overview page is in the generated llms.txt / llms-full.txt, and reword the description to say the index covers the guide and Python API (the C/C++ reference stays browsable on the site). The generated mkdoxy pages are deliberately not listed so the strict build keeps no dependency on plugin ordering. * docs(changelog): record the docs-site migration and versioned-docs setup The Unreleased section logged the rebrand and the CI/review fixes but not the headline change this branch makes: migrating the docs site into the repo with mike versioning, mkdoxy/mkdocstrings API reference, notebook example pages, and the llms.txt index. * docs: adding helper function to correctly copy into the doc strings from cuvis-il wip * docs: updating version of used docker containers --------- Co-authored-by: Nima Ghorbani <nima.gbani@gmail.com>
1 parent 2925eff commit 62860e2

22 files changed

Lines changed: 809 additions & 41 deletions

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

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
name: Deploy versioned docs (mike)
2+
3+
on:
4+
push:
5+
tags:
6+
- "v*.*.*"
7+
8+
permissions:
9+
contents: write
10+
11+
concurrency:
12+
group: docs-deploy
13+
cancel-in-progress: false
14+
15+
jobs:
16+
deploy:
17+
runs-on: ubuntu-latest
18+
container:
19+
image: cubertgmbh/cuvis_pyil:3.5.3-ubuntu24.04
20+
steps:
21+
- name: Install build dependencies
22+
run: apt-get update -y && apt-get install -y git doxygen graphviz
23+
24+
- uses: actions/checkout@v4
25+
with:
26+
fetch-depth: 0
27+
submodules: recursive
28+
29+
- name: Stage cuvis.h for Doxygen
30+
run: |
31+
mkdir -p docs/_api_sources
32+
cp /usr/include/cuvis.h docs/_api_sources/cuvis.h
33+
34+
- name: Install uv
35+
uses: astral-sh/setup-uv@v4
36+
with:
37+
enable-cache: true
38+
39+
- name: Sync docs deps
40+
run: uv venv --system-site-packages && uv sync --extra docs
41+
42+
- name: Configure git for mike
43+
run: |
44+
git config user.name "github-actions[bot]"
45+
git config user.email "github-actions[bot]@users.noreply.github.com"
46+
47+
- name: Build docs (strict)
48+
run: uv run mkdocs build --strict
49+
50+
- name: Get version from tag
51+
id: get_version
52+
run: |
53+
VERSION="${{ github.ref_name }}"
54+
VERSION="${VERSION#v}"
55+
echo "VERSION=${VERSION}" >> "$GITHUB_OUTPUT"
56+
57+
- name: Deploy docs with mike
58+
run: |
59+
uv run mike deploy --push --update-aliases ${{ steps.get_version.outputs.VERSION }} latest
60+
uv run mike set-default --push latest

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

Lines changed: 26 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -1,55 +1,50 @@
1-
name: Deploy docs to GitHub Pages
1+
name: Deploy docs to GitHub Pages (nightly)
22

33
on:
44
push:
55
branches: [main]
6-
paths:
7-
- docs/**
8-
- tools/**
9-
- scripts/cuvis_sdk_url.py
10-
- mkdocs.yml
11-
- pyproject.toml
12-
- uv.lock
13-
- .github/workflows/deploy-docs.yml
14-
workflow_dispatch:
156

167
permissions:
17-
contents: read
18-
pages: write
19-
id-token: write
8+
contents: write
209

2110
concurrency:
22-
group: pages
11+
group: docs-deploy
2312
cancel-in-progress: false
2413

2514
jobs:
26-
build:
15+
deploy:
2716
runs-on: ubuntu-latest
17+
container:
18+
image: cubertgmbh/cuvis_pyil:3.5.3-ubuntu24.04
2819
steps:
20+
- name: Install build dependencies
21+
run: apt-get update -y && apt-get install -y git doxygen graphviz
22+
2923
- uses: actions/checkout@v4
24+
with:
25+
fetch-depth: 0
26+
submodules: recursive
27+
28+
- name: Stage cuvis.h for Doxygen
29+
run: |
30+
mkdir -p docs/_api_sources
31+
cp /usr/include/cuvis.h docs/_api_sources/cuvis.h
3032
3133
- name: Install uv
3234
uses: astral-sh/setup-uv@v4
3335
with:
3436
enable-cache: true
3537

3638
- name: Sync docs deps
37-
run: uv sync --extra docs
39+
run: uv venv --system-site-packages && uv sync --extra docs
3840

39-
- name: Build site
40-
run: uv run mkdocs build --strict
41+
- name: Configure git for mike
42+
run: |
43+
git config user.name "github-actions[bot]"
44+
git config user.email "github-actions[bot]@users.noreply.github.com"
4145
42-
- name: Upload Pages artifact
43-
uses: actions/upload-pages-artifact@v3
44-
with:
45-
path: site
46+
- name: Build docs (strict)
47+
run: uv run mkdocs build --strict
4648

47-
deploy:
48-
needs: build
49-
runs-on: ubuntu-latest
50-
environment:
51-
name: github-pages
52-
url: ${{ steps.deployment.outputs.page_url }}
53-
steps:
54-
- id: deployment
55-
uses: actions/deploy-pages@v4
49+
- name: Deploy dev (nightly) docs
50+
run: uv run mike deploy --push dev

‎.github/workflows/docs-check.yml‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
name: Docs build check
2+
3+
on:
4+
pull_request:
5+
branches: [main]
6+
7+
permissions:
8+
contents: read
9+
10+
concurrency:
11+
group: docs-check-${{ github.ref }}
12+
cancel-in-progress: true
13+
14+
jobs:
15+
build:
16+
runs-on: ubuntu-latest
17+
container:
18+
image: cubertgmbh/cuvis_pyil:3.5.3-ubuntu24.04
19+
steps:
20+
- name: Install build dependencies
21+
run: apt-get update -y && apt-get install -y git doxygen graphviz
22+
23+
- uses: actions/checkout@v4
24+
with:
25+
fetch-depth: 0
26+
submodules: recursive
27+
28+
- name: Stage cuvis.h for Doxygen
29+
run: |
30+
mkdir -p docs/_api_sources
31+
cp /usr/include/cuvis.h docs/_api_sources/cuvis.h
32+
33+
- name: Install uv
34+
uses: astral-sh/setup-uv@v4
35+
with:
36+
enable-cache: true
37+
38+
- name: Sync docs deps
39+
run: uv venv --system-site-packages && uv sync --extra docs
40+
41+
- name: Build site (strict)
42+
run: uv run mkdocs build --strict

‎.gitignore‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,3 +44,11 @@ _assets/
4444
# uv-managed virtual envs and mkdocs build output.
4545
.venv/
4646
site/
47+
48+
# mkdoxy-generated API reference pages (regenerated at each mkdocs build)
49+
docs/cuvis_c/
50+
docs/cuvis_cpp/
51+
52+
# cuvis.h is sourced from the installed SDK at build time, not version-controlled.
53+
# Use scripts/fetch-cuvis-header.sh locally or the CI "Extract cuvis.h" step.
54+
docs/_api_sources/

‎CHANGELOG.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,4 +2,11 @@
22

33
## Unreleased
44

5+
- **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`.
56
- 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.
7+
- **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.
8+
- **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`.
9+
- **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).
10+
- **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.
11+
- **Fixed a Material theme feature typo** in `mkdocs.yml` (`content.code.annotation` → `content.code.annotate`) so code annotations render.
12+
- **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‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
# Python API Reference
2+
3+
The Python wrapper mirrors the C and C++ API concepts. Signatures shown here
4+
are derived from static analysis of the source; see the C/C++ API reference
5+
for full parameter-level documentation.
6+
7+
## General
8+
9+
::: cuvis.General
10+
options:
11+
members: [init, shutdown, version, set_log_level]
12+
show_source: false
13+
14+
## SessionFile
15+
16+
::: cuvis.SessionFile
17+
options:
18+
show_source: false
19+
20+
## Measurement
21+
22+
::: cuvis.Measurement
23+
options:
24+
show_source: false
25+
26+
## ProcessingContext
27+
28+
::: cuvis.ProcessingContext
29+
options:
30+
show_source: false
31+
32+
## AcquisitionContext
33+
34+
::: cuvis.AcquisitionContext
35+
options:
36+
show_source: false
37+
38+
## Worker
39+
40+
::: cuvis.Worker
41+
options:
42+
show_source: false
43+
44+
## Viewer
45+
46+
::: cuvis.Viewer
47+
options:
48+
show_source: false
49+
50+
## Calibration
51+
52+
::: cuvis.Calibration
53+
options:
54+
show_source: false
55+
56+
## Export
57+
58+
::: cuvis.Export
59+
options:
60+
show_source: false
61+
62+
## Types & Enums
63+
64+
::: cuvis.cuvis_types
65+
options:
66+
show_source: false
67+
members_order: alphabetical

‎docs/examples/example_1_take_snapshot.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
{{ multilang_example("Example_1_Take_Snapshot") }}

‎docs/examples/example_2_load_measurement.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
{{ multilang_example("Example_2_Load_Measurement") }}

‎docs/examples/example_3_reprocess.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
{{ multilang_example("Example_3_Reprocess") }}

‎docs/examples/example_4_exporters.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
{{ multilang_example("Example_4_Exporters") }}

0 commit comments

Comments
 (0)