kindred/create
1
1
Fork 0
Code Issues 37 Pull Requests Actions Packages Projects 9 Releases 2 Wiki Activity

docs: comprehensive documentation refresh — remove stale references, add missing content
All checks were successful
Build and Test / build (pull_request) Successful in 24m46s
Details

Browse Source 
Root documentation:
- README.md: add Datums description, update addon load order and SDK references,
  fix project structure tree, update issue reporting guidance
- CONTRIBUTING.md: update submodule table (remove ztools, add gears/datums/solver),
  fix QSS guidance (single canonical source, not three copies)
- docs/ARCHITECTURE.md: update bootstrap flow (5 addons, split deferred timers
  between Create core and Silo addon), update load order and source layout
- docs/COMPONENTS.md: add Datums and Solver sections, update Gears description,
  fix Silo origin registration reference
- docs/KNOWN_ISSUES.md: create missing file referenced by CLAUDE.md and CONTRIBUTING.md
- docs/INTEGRATION_PLAN.md: update layer 5 diagram, fix load order references,
  update Phase 6 install rules, fix Layer 2/3/5 descriptions
- docs/OVERVIEW.md: add datums submodule entry
- docs/UPSTREAM.md: update Phase 1 directory table and Phase 4 submodule list

mdBook documentation (docs/src/):
- SUMMARY.md: replace dead architecture/ links with existing reference pages,
  remove deleted silo-server files, add new silo-server pages
- introduction.md: rewrite — replace ztools with current addons (Silo, Gears,
  Datums, KCSDK), update version to v0.1.5/FreeCAD 1.2.0
- guide/getting-started.md: update first-run addon list
- guide/installation.md: update verification console output
- guide/workbenches.md: rewrite — replace ztools with Gears, Datums, Solver
- guide/building.md: update submodule table, fix error message guidance
- development/contributing.md: fix scope example and issue reporting
- development/repo-structure.md: rewrite — add SDK, datums, gears, solver,
  reference/ folder; update submodule and key files tables
- development/writing-an-addon.md: fix priority range table
- reference/create-module-bootstrap.md: rewrite — reflect addon_loader system,
  split deferred timers between Create core and Silo addon
- reference/datum-creator.md: update from ZTools to datums addon paths and naming
- reference/glossary.md: add KCSDK entry, update FreeCAD version, remove ztools
  entry, update repository URLs table
This commit is contained in:
forbes
2026-03-03 13:52:53 -06:00
parent 53f39d6368
commit 7f02fd182e
20 changed files with 247 additions and 155 deletions
Download Patch File Download Diff File Expand all files Collapse all files

105
docs/src/reference/create-module-bootstrap.md
View File

@@ -5,41 +5,42 @@ The Create module (`src/Mod/Create/`) is the integration layer that bootstraps K
**Source files:**
- `src/Mod/Create/Init.py` -- console-phase addon loading
- `src/Mod/Create/InitGui.py` -- GUI-phase workbench loading and deferred timers
- `src/Mod/Create/InitGui.py` -- GUI-phase addon loading and deferred timers
- `src/Mod/Create/addon_loader.py` -- manifest-driven loader with dependency resolution
- `src/Mod/Create/update_checker.py` -- Gitea releases API polling
- `src/Mod/Create/kc_format.py` -- .kc file format round-trip preservation
## Loading Mechanism
FreeCAD loads module `Init.py` and `InitGui.py` files using **direct `exec()`**, not Python's import system. The C++ startup code scans `Mod/` directories, reads each file as text, compiles it, and executes it in an isolated namespace:
FreeCAD loads module `Init.py` and `InitGui.py` files using **direct `exec()`**, not Python's import system. The C++ startup code scans `Mod/` directories, reads each file as text, compiles it, and executes it in an isolated namespace.
```python
source = init_py.read_text(encoding="utf-8")
code = compile(source, init_py, "exec")
exec(code)
```
Modules loaded this way are **not** added to `sys.modules`. Each execution gets a fresh globals dict with no caching or dependency resolution.
The addon loader (`addon_loader.py`) then discovers addons in `mods/` via their `package.xml` manifests, resolves dependencies via topological sort, and loads them in priority order.
## Phase 1: Console (`Init.py`)
Runs immediately at application startup, before any GUI is available.
`setup_kindred_addons()` discovers and loads two built-in addons from `mods/`:
`addon_loader.load_addons(gui=False)` discovers and loads addons from `mods/`:
| Addon | Path | Purpose |
|-------|------|---------|
| ztools | `mods/ztools/ztools/` | Part design, assembly, and sketcher tools |
| silo | `mods/silo/freecad/` | Database integration and version control |
| Addon | Priority | Purpose |
|-------|----------|---------|
| sdk | 0 | Stable API contract |
| solver | 10 | Assembly solver research |
| gears | 40 | Parametric gear generation |
| datums | 45 | Unified datum creator |
| silo | 60 | PLM workbench |
For each addon:
1. Build the path from `FreeCAD.getHomePath() + "mods/" + addon_path`
2. Add to `sys.path` if not already present
3. Find `Init.py` in the addon directory
4. Execute it with `exec(compile(source, init_file, "exec"), exec_globals)`
1. Discover `package.xml` manifest (depth 1 or 2)
2. Parse `<kindred>` extensions (version bounds, priority, dependencies)
3. Validate version compatibility
4. Resolve load order via topological sort on dependencies
5. Add addon dir to `sys.path`
6. Execute `Init.py`
7. Register in `FreeCAD.KindredAddons`
Failures are logged to `FreeCAD.Console.PrintWarning()` and do not prevent other addons from loading.
Failures are logged to `FreeCAD.Console` and do not prevent other addons from loading.
## Phase 2: GUI (`InitGui.py`)
@@ -47,35 +48,36 @@ Runs after the console phase, when `FreeCADGui` is available.
### Synchronous
`setup_kindred_workbenches()` loads `InitGui.py` from the same two addons (ztools, silo), registering their workbenches and GUI commands.
`addon_loader.load_addons(gui=True)` loads `InitGui.py` from each addon in the same resolved order, registering workbenches and GUI commands.
### Deferred Timers
### Deferred Timers (Create core)
Six `QTimer.singleShot` calls stagger initialization to let the GUI event loop settle:
Two `QTimer.singleShot` calls in `src/Mod/Create/InitGui.py`:
| Delay | Function | Purpose |
|-------|----------|---------|
| 500 ms | `_register_kc_format()` | Register .kc file format observer |
| 1500 ms | `_register_silo_origin()` | Register Silo as a file origin |
| 2000 ms | `_setup_silo_auth_panel()` | Dock the Database Auth panel |
| 3000 ms | `_check_silo_first_start()` | Show settings dialog on first run |
| 4000 ms | `_setup_silo_activity_panel()` | Dock the Database Activity panel |
| 10000 ms | `_check_for_updates()` | Poll Gitea for new releases |
Every timer callback is wrapped in `try/except`. Failures log to `FreeCAD.Console.PrintLog()` and do not crash the application.
### Deferred Timers (Silo addon)
The Silo addon manages its own deferred setup in `mods/silo/InitGui.py`:
| Delay | Function | Purpose |
|-------|----------|---------|
| 500 ms | `_handle_startup_urls()` | Process kindred:// URLs |
| 600 ms | `_register_silo_document_observer()` | .kc tree building observer |
| 2000 ms | `_setup_silo_auth_panel()` | "Database Auth" dock panel |
| 2500 ms | Silo overlay registration | "Silo Origin" toolbar overlay |
| 3000 ms | `_check_silo_first_start()` | Settings prompt on first run |
| 4000 ms | `_setup_silo_activity_panel()` | "Database Activity" dock panel |
Every timer callback is wrapped in `try/except`. Failures log to `FreeCAD.Console` and do not crash the application.
### Timer Details
**_register_kc_format (500 ms)** -- Imports `kc_format` and calls `kc_format.register()`, which installs a `DocumentObserver` with `slotStartSaveDocument` / `slotFinishSaveDocument` hooks. These cache `silo/` ZIP entries before FreeCAD's C++ save rewrites the archive, then re-inject them afterwards. Only processes `.kc` files.
**_register_silo_origin (1500 ms)** -- Imports `silo_origin` and calls `silo_origin.register_silo_origin()`, making Silo available in the origin selector dropdown alongside LocalFileOrigin.
**_setup_silo_auth_panel (2000 ms)** -- Creates a `QDockWidget` titled "Database Auth" containing a `SiloAuthDockWidget` from `silo_commands`. Docked on the right side of the main window. Guards against duplicates by checking if the widget already exists.
**_check_silo_first_start (3000 ms)** -- Reads `User parameter:BaseApp/Preferences/Mod/KindredSilo`. On the very first launch (when `FirstStartChecked` is not set), runs the `Silo_Settings` command if no API URL is configured.
**_setup_silo_activity_panel (4000 ms)** -- Creates a "Database Activity" dock widget showing the 20 most recent Silo items (part number, description, date). Falls back to "(Unable to connect to Silo database)" on connection failure.
**_check_for_updates (10000 ms)** -- Calls `update_checker._run_update_check()` in the background.
## Update Checker
@@ -112,21 +114,32 @@ The checker never shows a dialog -- it only logs to `FreeCAD.Console`.
FreeCAD startup
|
Init.py (exec'd, immediate)
+-- setup_kindred_addons()
| +-- ztools/Init.py (exec'd)
| +-- silo/freecad/Init.py (exec'd)
+-- addon_loader.load_addons(gui=False)
| +-- sdk/Init.py
| +-- solver/Init.py
| +-- gears/Init.py
| +-- datums/Init.py
| +-- silo/Init.py
|
[GUI startup]
|
InitGui.py (exec'd, immediate)
+-- setup_kindred_workbenches()
| +-- ztools/InitGui.py (exec'd)
| +-- silo/freecad/InitGui.py (exec'd)
+-- addon_loader.load_addons(gui=True)
| +-- sdk/InitGui.py
| +-- solver/InitGui.py
| +-- gears/InitGui.py
| +-- datums/InitGui.py
| +-- silo/InitGui.py (schedules its own deferred timers)
|
+-- QTimer 500ms --> kc_format.register()
+-- QTimer 1500ms --> silo_origin.register_silo_origin()
+-- QTimer 2000ms --> SiloAuthDockWidget
+-- QTimer 3000ms --> Silo first-start check
+-- QTimer 4000ms --> Database Activity panel
Create core timers:
+-- QTimer 500ms --> kc_format.register()
+-- QTimer 10000ms --> update_checker._run_update_check()
Silo addon timers (scheduled from silo/InitGui.py):
+-- QTimer 500ms --> kindred:// URL handler
+-- QTimer 600ms --> document observer
+-- QTimer 2000ms --> auth dock panel
+-- QTimer 2500ms --> Silo overlay
+-- QTimer 3000ms --> first-start check
+-- QTimer 4000ms --> activity dock panel
```

21
docs/src/reference/datum-creator.md
View File

@@ -1,11 +1,14 @@
# Datum Creator System
The ZTools Datum Creator (`ZTools_DatumCreator`) creates parametric datum planes, axes, and points. It auto-detects the datum type from selected geometry and provides a unified task panel with 16 creation modes.
The Datum Creator (`Create_DatumCreator`) creates parametric datum planes, axes, and points. It auto-detects the datum type from selected geometry and provides a unified task panel with 16 creation modes.
**Source files:**
- `mods/ztools/ztools/ztools/commands/datum_commands.py` -- UI, selection handling, mode detection
- `mods/ztools/ztools/ztools/datums/core.py` -- geometry computation and FreeCAD object creation
- `mods/datums/datums/command.py` -- UI, selection handling, mode detection
- `mods/datums/datums/core.py` -- geometry computation and FreeCAD object creation
- `mods/datums/datums/detection.py` -- auto-detection algorithm
- `mods/datums/datums/panel.py` -- task panel UI
- `mods/datums/datums/edit_panel.py` -- edit panel with real-time parameter updates
## Geometry Classification
@@ -90,7 +93,7 @@ The detected mode is displayed with a category color:
```
+-------------------------------------+
| ZTools Datum Creator |
| Datum Creator |
+-------------------------------------+
| Selection |
| [icon] Element Name [Remove] |
@@ -167,11 +170,7 @@ Each `core.*` function:
1. Creates the FreeCAD object (`PartDesign::Plane` in a body, `Part::Plane` at document level)
2. Computes the placement from the source geometry
3. Configures attachment (MapMode, AttachmentSupport, offset) for parametric updates
4. Stores ZTools metadata in custom properties:
- `ZTools_Type` -- creation method identifier (e.g. `"offset_from_face"`)
- `ZTools_Params` -- parameters as JSON (e.g. `{"distance": 10}`)
- `ZTools_SourceRefs` -- source geometry references as JSON
5. Applies Catppuccin Mocha styling (mauve at 70% transparency for planes)
6. Optionally links parameters to a spreadsheet alias
4. Applies Catppuccin Mocha styling (mauve at 70% transparency for planes)
5. Optionally links parameters to a spreadsheet alias
Auto-naming uses the format `ZPlane_Offset_001`, incrementing the index for each new datum of the same type.
Auto-naming uses the format `DatumPlane_Offset_001`, incrementing the index for each new datum of the same type.

12
docs/src/reference/glossary.md
View File

@@ -12,11 +12,13 @@
**FileOrigin** — Abstract C++ interface in `src/Gui/` that defines a pluggable file backend. Implementations: `LocalFileOrigin` (filesystem) and `SiloOrigin` (database).
**FreeCAD** — Open-source parametric 3D CAD platform. Kindred Create is based on FreeCAD v1.0.0. Website: <https://www.freecad.org>
**FreeCAD** — Open-source parametric 3D CAD platform. Kindred Create is based on FreeCAD v1.2.0. Website: <https://www.freecad.org>
**Kindred Create** — The full application: a FreeCAD fork plus Kindred's addon workbenches, theme, and tooling.
**Manipulator** — FreeCAD mechanism for injecting commands from one workbench into another's menus and toolbars. Used by ztools to add commands to PartDesign.
**KCSDK** — Kindred Create SDK. A C++ shared library (`libKCSDK`) with pybind11 bindings (`kcsdk` Python module) providing stable interfaces for dock panels, toolbars, menus, themes, and editing contexts.
**Manipulator** — FreeCAD mechanism for injecting commands from one workbench into another's menus and toolbars.
**MinIO** — S3-compatible object storage server. Used by Silo to store binary `.FCStd` files.
@@ -38,15 +40,15 @@
**Workbench** — FreeCAD's plugin/module system. Each workbench provides a set of tools, menus, and toolbars for a specific task domain.
**ztools** — Kindred's unified workbench combining Part Design, Assembly, and Sketcher tools with custom datum creation and assembly patterns.
## Repository URLs
| Repository | URL |
|------------|-----|
| Kindred Create | <https://git.kindred-systems.com/kindred/create> |
| ztools | <https://git.kindred-systems.com/forbes/ztools> |
| silo-mod | <https://git.kindred-systems.com/kindred/silo-mod> |
| gears | <https://git.kindred-systems.com/kindred/gears> |
| datums | <https://git.kindred-systems.com/kindred/datums> |
| solver | <https://git.kindred-systems.com/kindred/solver> |
| OndselSolver | <https://git.kindred-systems.com/kindred/solver> |
| GSL | <https://github.com/microsoft/GSL> |
| AddonManager | <https://github.com/FreeCAD/AddonManager> |