Merge pull request #14 from torusJKL/add-docstrings

- Add docstrings for all public functions
- Use Staple to generate documentation pages

Author: torusJKL

.github/workflows/docs.yml

@@ -0,0 +1,54 @@
+name: docs
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install system dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y cmake g++ sbcl curl just libfreetype-dev libx11-dev libfontconfig-dev libgl1-mesa-dev
+
+      - name: Install Quicklisp
+        run: |
+          curl -O https://beta.quicklisp.org/quicklisp.lisp
+          sbcl --load quicklisp.lisp \
+               --eval "(quicklisp-quickstart:install)" \
+               --quit
+
+      - name: Get OCCT version
+        run: |
+          echo "OCCT_VERSION=$(grep -oP '(?<=occt-version := ")[^"]+' justfile)" >> $GITHUB_ENV
+
+      - name: Cache OCCT build
+        id: cache-occt
+        uses: actions/cache@v4
+        with:
+          path: .local
+          key: occt-${{ env.OCCT_VERSION }}-visual
+
+      - name: Build OCCT (cache miss)
+        if: steps.cache-occt.outputs.cache-hit != 'true'
+        run: |
+          just setup 2>&1 | tail -500
+          exit ${PIPESTATUS[0]}
+
+      - name: Build C wrapper
+        run: just wrap
+
+      - name: Generate Staple docs
+        run: just docs
+
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs
+          publish_branch: gh-pages

.gitignore

@@ -3,3 +3,4 @@ lib/
 *.step
 *.fasl
 *.fas
+docs/

justfile

@@ -17,6 +17,7 @@ default:
     @echo "  wrap        Compile C wrapper → lib/libocctwrap.so"
     @echo "  start       Launch SBCL REPL with cl-occt loaded (via Quicklisp)"
     @echo "  repl        Launch SBCL REPL with cl-occt loaded (standalone)"
+    @echo "  docs        Generate Staple HTML documentation into docs/"
     @echo "  test-core   Run ~200 core tests (geometry, I/O, DAG) — no X display needed"
     @echo "  test-viewer Run ~80 viewer tests (rendering, AIS, camera) — needs xvfb-run"
     @echo "  test-all    Run all 288 tests under xvfb-run"
@@ -72,6 +73,18 @@ repl:
 clean:
     rm -rf {{occt-build}} {{occt-src}} {{occt-tarball}}
 
+docs:
+    # Generate Staple HTML documentation
+    mkdir -p {{root-dir}}/docs
+    LD_LIBRARY_PATH={{root-dir}}/lib:{{occt-install}}/lib \
+    {{sbcl}} --load ~/quicklisp/setup.lisp \
+            --eval "(push \"{{root-dir}}/\" asdf:*central-registry*)" \
+            --eval "(ql:quickload :staple)" \
+            --eval "(ql:quickload :staple-markdown)" \
+            --eval "(ql:quickload :cl-occt)" \
+            --eval "(staple:generate :cl-occt :if-exists :supersede :output-directory #p\"{{root-dir}}/docs/\")" \
+            --quit
+
 test-core:
     # Run core tests (geometry, I/O, DAG, colors, text shapes) — no X display needed
     LD_LIBRARY_PATH={{root-dir}}/lib:{{occt-install}}/lib \

openspec/changes/archive/2026-05-24-docstrings-analysis/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-05-23

openspec/changes/archive/2026-05-24-docstrings-analysis/design.md

@@ -0,0 +1,24 @@
+## Context
+
+Six files span geometry algorithms (projection, intersection, interpolation), physical properties (volume, area, center of mass), shape validity checking, shape fixing/healing, and NURBS rebuild. These are the most mathematically complex functions in cl-occt.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Every public function gets docstring with example
+- Parameter descriptions for functions with many parameters (e.g., `interpolate-points`, `substitute-shape`)
+- `See also:` linking between related functions (`shape-volume` ↔ `shape-area` ↔ `shape-center-of-mass`)
+
+**Non-Goals:**
+- No functional or API changes
+
+## Decisions
+
+- **Geometry algorithm examples** should use simple known shapes (box, sphere) as test inputs
+- **Mass properties examples** should show `gprops` object accessors
+- **Shape fix examples** can use `shape-check` to demonstrate validation before/after fix
+- **Shape rebuild examples** should show degree reduction and continuity upgrade on a known shape
+
+## Risks / Trade-offs
+
+- **Interpolation and NURBS conversion** examples are inherently long — maintain readability

openspec/changes/archive/2026-05-24-docstrings-analysis/proposal.md

@@ -0,0 +1,30 @@
+## Why
+
+The geometry analysis, mass properties, shape analysis, shape fix, shape healing, and shape rebuild functions are powerful but opaque. Users need docstrings to understand parameters for operations like point projection, curve intersection, shape distance, volume/area calculation, shape fixing, and NURBS conversion.
+
+## What Changes
+
+- Add docstrings with `Example:` blocks to all public functions across 6 analysis/healing files
+- No functional or API changes — documentation only
+
+Files modified: `src/core/geom-algorithms.lisp`, `src/core/mass-properties.lisp`, `src/core/shape-analysis.lisp`, `src/core/shape-fix.lisp`, `src/core/shape-process.lisp`, `src/core/shape-rebuild.lisp`
+
+## Capabilities
+
+### New Capabilities
+
+None — documentation enhancement only.
+
+### Modified Capabilities
+
+None — no spec-level behavior changes.
+
+## Impact
+
+- `src/core/geom-algorithms.lisp`: 11 functions — `project-point-on-curve`, `project-point-on-surface`, `intersect-curves`, `intersect-curve-surface`, `intersect-surfaces`, `extrema-curve-curve`, `extrema-curve-surface`, `intersect-curves-2d`, `project-point-on-curve-2d`, `points-to-bspline`, `interpolate-points`
+- `src/core/mass-properties.lisp`: 5 functions — `shape-gprops`, `shape-volume`, `shape-area`, `shape-center-of-mass`, `shape-inertia`
+- `src/core/shape-analysis.lisp`: 7 functions — `shape-distance`, `shape-distance-extrema`, `point-in-solid-p`, `classify-point-in-solid`, `shape-valid-p`, `shape-check`, `intersect-curve-shape`
+- `src/core/shape-fix.lisp`: 9 functions — `fix-shape`, `fix-wire`, `fix-solid`, `fix-edge`, `fix-face`, `shape-analysis-free-edges`, `shape-analysis-check-intersections`, `shape-analysis-wire-contains-p`, `shape-analysis-contents`
+- `src/core/shape-process.lisp`: 3 functions — `apply-shape-process`, `apply-healing-pipeline`, `heal-shape`
+- `src/core/shape-rebuild.lisp`: 6 functions — `substitute-shape`, `shape-to-nurbs`, `shape-reduce-degree`, `shape-to-rational-bspline`, `shape-split-u`, `shape-upgrade-continuity`
+- All existing tests should pass unchanged

openspec/changes/archive/2026-05-24-docstrings-analysis/specs/no-functional-changes.md

@@ -0,0 +1 @@
+This change is documentation-only. No spec-level behavior changes.

openspec/changes/archive/2026-05-24-docstrings-analysis/tasks.md

@@ -0,0 +1,62 @@
+## 1. Geometry algorithms (`geom-algorithms.lisp`)
+
+- [x] 1.1 Add docstring + example to `project-point-on-curve`
+- [x] 1.2 Add docstring + example to `project-point-on-surface`
+- [x] 1.3 Add docstring + example to `intersect-curves`
+- [x] 1.4 Add docstring + example to `intersect-curve-surface`
+- [x] 1.5 Add docstring + example to `intersect-surfaces`
+- [x] 1.6 Add docstring + example to `extrema-curve-curve`
+- [x] 1.7 Add docstring + example to `extrema-curve-surface`
+- [x] 1.8 Add docstring + example to `intersect-curves-2d`
+- [x] 1.9 Add docstring + example to `project-point-on-curve-2d`
+- [x] 1.10 Add docstring + example to `points-to-bspline`
+- [x] 1.11 Add docstring + example to `interpolate-points`
+
+## 2. Mass properties (`mass-properties.lisp`)
+
+- [x] 2.1 Add docstring + example to `shape-gprops`
+- [x] 2.2 Add docstring + example to `shape-volume`
+- [x] 2.3 Add docstring + example to `shape-area`
+- [x] 2.4 Add docstring + example to `shape-center-of-mass`
+- [x] 2.5 Add docstring + example to `shape-inertia`
+
+## 3. Shape analysis (`shape-analysis.lisp`)
+
+- [x] 3.1 Add docstring + example to `shape-distance`
+- [x] 3.2 Add docstring + example to `shape-distance-extrema`
+- [x] 3.3 Add docstring + example to `point-in-solid-p`
+- [x] 3.4 Add docstring + example to `classify-point-in-solid`
+- [x] 3.5 Add docstring + example to `shape-valid-p`
+- [x] 3.6 Add docstring + example to `shape-check`
+- [x] 3.7 Add docstring + example to `intersect-curve-shape`
+
+## 4. Shape fix (`shape-fix.lisp`)
+
+- [x] 4.1 Add docstring + example to `fix-shape`
+- [x] 4.2 Add docstring + example to `fix-wire`
+- [x] 4.3 Add docstring + example to `fix-solid`
+- [x] 4.4 Add docstring + example to `fix-edge`
+- [x] 4.5 Add docstring + example to `fix-face`
+- [x] 4.6 Add docstring + example to `shape-analysis-free-edges`
+- [x] 4.7 Add docstring + example to `shape-analysis-check-intersections`
+- [x] 4.8 Add docstring + example to `shape-analysis-wire-contains-p`
+- [x] 4.9 Add docstring + example to `shape-analysis-contents`
+
+## 5. Shape process (`shape-process.lisp`)
+
+- [x] 5.1 Add docstring + example to `apply-shape-process`
+- [x] 5.2 Add docstring + example to `apply-healing-pipeline`
+- [x] 5.3 Add docstring + example to `heal-shape`
+
+## 6. Shape rebuild (`shape-rebuild.lisp`)
+
+- [x] 6.1 Add docstring + example to `substitute-shape`
+- [x] 6.2 Add docstring + example to `shape-to-nurbs`
+- [x] 6.3 Add docstring + example to `shape-reduce-degree`
+- [x] 6.4 Add docstring + example to `shape-to-rational-bspline`
+- [x] 6.5 Add docstring + example to `shape-split-u`
+- [x] 6.6 Add docstring + example to `shape-upgrade-continuity`
+
+## 7. Verification
+
+- [x] 7.1 Run `just test-core` to verify no breakage

openspec/changes/archive/2026-05-24-docstrings-core-primitives/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-05-23

openspec/changes/archive/2026-05-24-docstrings-core-primitives/design.md

@@ -0,0 +1,42 @@
+## Context
+
+The `cl-occt` package has 381 public API functions, none of which have docstrings with examples. This change targets 17 functions across 5 files that form the core geometric primitives, boolean operations, transforms, compounds, and shape predicate.
+
+The user-provided `cut` example establishes the docstring convention:
+- Description line explaining what the function does
+- Parameter descriptions for complex functions
+- `Example:` block with REPL-style usage
+- `See also:` cross-references to related functions
+
+## Goals / Non-Goals
+
+**Goals:**
+- Every public function in the target files gets a docstring
+- Every non-trivial docstring includes a usage example
+- Trivial predicates (`shape-p`) get a docstring description without example
+- Cross-reference related functions via `See also:` where natural
+
+**Non-Goals:**
+- No functional or API changes
+- No changes to internal (`%`-prefixed or `cl-occt.impl` package) functions
+- No changes to test files
+- No changes to existing specs
+
+## Decisions
+
+**Docstring format** — Loose template, not rigid:
+  - Simple creators (`make-box`): description + brief example showing call with args
+  - Boolean ops (`cut`/`fuse`/etc.): description + example showing `display` and `def` usage + `See also:`
+  - Accessors (`compound-shape-p`): description + short example
+  - Trivial predicates (`shape-p`): description only
+
+**Example style** — REPL output is shown as comments. Examples should be self-contained where possible. For boolean ops, use `def` for intermediate shapes and `display` for result visualization (matching the user's `cut` example style).
+
+**Cross-references** — `See also:` with backtick-quoted function names. For related groups (booleans, primitives), list sibling functions.
+
+**No specs needed** — This is a documentation-only change. No requirement behavior changes.
+
+## Risks / Trade-offs
+
+- **Inconsistency risk** → Multiple files touched, but following the established `cut` example as a style guide minimizes drift
+- **No automated validation** → Docstring correctness isn't testable. Manual review is the only check.