Add docstrings & documentation generation - #14
Merged
Merged
Conversation
torusJKL
commented
May 24, 2026
torusJKL
commented
Owner
- Add docstrings for all public functions
- Use Staple to generate documentation pages
…, compounds, shape-p 17 functions across 5 files gain docstrings with REPL-style examples. - primitives.lisp: make-box, make-cylinder, make-sphere, make-cone, make-torus, make-prism (uses make-circle-edge), make-revol (uses rectangular 2D face profile) - booleans.lisp: cut, fuse, common, section — with See also cross-refs - transforms.lisp: translate, rotate - compounds.lisp: make-compound, add-to-compound, compound-shape-p - shape.lisp: shape-p (trivial predicate, description only) All 376 core tests pass.
Add docstring and Example: blocks to all 16 public functions in faces.lisp (make-edge, make-edge-3d, make-circle-edge, make-circular-arc, make-wire, make-face, make-face-on-plane) and topology.lisp (map-shape-subshapes, count-shape-subshapes, dump-shape, shape-triangle-count, wire-order-check-p, edge->curve, face->surface, make-vertex, make-polygon). Includes See also: cross-references between related functions. No functional or API changes — documentation only.
…hape fix, shape process, and shape rebuild functions 41 functions across 6 files now have docstrings with parameter descriptions, Examples, and See also cross-references: - geom-algorithms.lisp: 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 - mass-properties.lisp: shape-gprops, shape-volume, shape-area, shape-center-of-mass, shape-inertia - shape-analysis.lisp: shape-distance, shape-distance-extrema, point-in-solid-p, classify-point-in-solid, shape-valid-p, shape-check, intersect-curve-shape - shape-fix.lisp: 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 - shape-process.lisp: apply-shape-process, apply-healing-pipeline, heal-shape - shape-rebuild.lisp: substitute-shape, shape-to-nurbs, shape-reduce-degree, shape-to-rational-bspline, shape-split-u, shape-upgrade-continuity Fix apply-shape-process docstring to list only actually supported operator names (from dispatch_operator in occt_wrap.cpp).
…nctions 16 files across features (fillet, chamfer, blend, draft, sweep, loft, pipe, shell, offset, local ops, holes, face filling, helix), assembly hierarchy, STEP/STL I/O, and error handling — each public function now has a docstring with description, Example: block, and See also: cross- references. No functional changes.
Document all 26 public functions in src/core/text.lisp: - Font creation: make-brep-font-from-file, make-brep-font-from-name - Text shaping: make-text-shape, make-text-shape-3d, make-text-shape-on-plane - Metrics: text-bounding-box, text-font-ascender/descender/line-spacing - Glyph ops: text-glyph-as-shape, text-glyph-as-shape-3d - AIS labels: make-ais-text-label, ais-free-text-label, setf accessors - Font queries: list-available-fonts, font-info, advance, scaling, curve mode - Multi-line: make-multi-line-text, make-formatted-text All 376 core tests pass.
73 functions across viewer lifecycle, AIS context, trihedron, grid, background, camera, and rendering — all now documented with descriptions and runnable examples. Files: src/core/viewer.lisp (46 functions + with-viewer macro) src/core/viewer-grid.lisp (10 functions) src/core/viewer-background.lisp ( 5 functions) src/core/viewer-camera.lisp (12 functions) src/core/viewer-rendering.lisp ( 8 functions)
Document all 111 public functions across 7 viewer styling files: - viewer-colors.lisp (14): colors, hex parsing, HLS, delta - viewer-defaults.lisp (8): background, projection, view size, lights - viewer-lighting.lisp (19): light CRUD, properties, queries - viewer-object-props.lisp (37): material, transparency, edges, tessellation, selection management, mouse detection, hilighting - viewer-drawer.lisp (14): line, shading, point, text, wire, boundary - viewer-dimensions.lisp (12): all dimension attribute setters - viewer-text-labels.lisp (7): angle, justification, display type, subtitle color, alignment No functional changes. All 484 tests pass.
- justfile: This is SBCL 2.6.0.debian, an implementation of ANSI Common Lisp. More information about SBCL is available at <http://www.sbcl.org/>. SBCL is free software, provided as is, with absolutely no warranty. It is mostly in the public domain; some portions are provided under BSD-style licenses. See the CREDITS and COPYING files in the distribution for more information. To load "staple": Load 1 ASDF system: staple ; Loading "staple" ................ To load "staple-markdown": Load 1 ASDF system: staple-markdown ; Loading "staple-markdown" ............................... To load "cl-occt": Load 1 ASDF system: cl-occt ; Loading "cl-occt" . To load "3bmd-ext-tables": Load 1 ASDF system: 3bmd-ext-tables ; Loading "3bmd-ext-tables" . To load "3bmd-ext-tables": Load 1 ASDF system: 3bmd-ext-tables ; Loading "3bmd-ext-tables" Scan was called 2375 times. Warning: could not find hyperspec map file. Adjust the path at the top of clhs-lookup.lisp to get links to the HyperSpec. Scan was called 1281 times. Scan was called 147 times. Scan was called 96 times. Scan was called 5138 times. Scan was called 2557 times. Scan was called 1387 times. Scan was called 1478 times. Scan was called 1422 times. Scan was called 2291 times. Scan was called 2350 times. Scan was called 3075 times. Scan was called 1193 times. Scan was called 1035 times. Scan was called 1720 times. Scan was called 814 times. Scan was called 942 times. Scan was called 1767 times. Scan was called 1010 times. Scan was called 940 times. Scan was called 728 times. Scan was called 468 times. Scan was called 594 times. Scan was called 400 times. Scan was called 643 times. Scan was called 1186 times. Scan was called 1156 times. Scan was called 915 times. Scan was called 8692 times. Scan was called 52 times. WARN: Error during code markup: Unquote not inside backquote. WARN: Error during code markup: Unquote not inside backquote. WARN: Error during code markup: Unquote not inside backquote. WARN: Error during code markup: Invalid function name: 1.0 WARN: Error during code markup: Symbol name must not end with a package marker (the : character). WARN: Error during code markup: Symbol name must not end with a package marker (the : character). WARN: Error during code markup: Invalid function name: 1.0 WARN: Error during code markup: An object must follow backquote. WARN: Error during code markup: A token consisting solely of multiple dots is illegal. WARN: Error during code markup: While reading list, expected the character ) when input ended. WARN: Error during code markup: A token consisting solely of multiple dots is illegal. WARN: Error during code markup: Invalid function name: 1.0 WARN: Error during code markup: Invalid function name: 1.0 WARN: Error during code markup: Symbol name must not end with a package marker (the : character). WARN: Error during code markup: Symbol name must not end with a package marker (the : character). WARN: Error during code markup: Symbol name must not end with a package marker (the : character). WARN: Error during code markup: A token consisting solely of multiple dots is illegal. WARN: Error during code markup: While reading list, expected the character ) when input ended. WARN: Error during code markup: Symbol name must not end with a package marker (the : character). WARN: Error during code markup: While reading backquote, expected an object when input ended. WARN: Error during code markup: While reading backquote, expected an object when input ended. recipe generates HTML via Staple - staple.ext.lisp: images/documents/subsystems overrides, custom template, title fix, 3bmd table support - .github/workflows/docs.yml: CI pipeline on push to main, builds OCCT (cached), runs Staple, deploys to gh-pages - staple-template.ctml: custom template with table CSS - .gitignore: ignore generated docs/
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.