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

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

View File

@@ -1,10 +1,10 @@
# Integration Plan
Strategy for integrating ztools and Silo as built-in addons while maintaining clear boundaries with FreeCAD core.
Strategy for integrating Kindred addons as built-in components while maintaining clear boundaries with FreeCAD core.
## Goals
1. **Native feel** -- ztools and Silo behave as first-class citizens, not bolted-on addons
1. **Native feel** -- Addons behave as first-class citizens, not bolted-on extras
2. **Clean boundaries** -- Clear separation between FreeCAD core, Kindred extensions, and addon code
3. **Minimal core modifications** -- Preserve FreeCAD's container models (Part, Body, Assembly)
4. **Maintainability** -- Easy to pull upstream FreeCAD changes without merge conflicts
@@ -18,12 +18,11 @@ Strategy for integrating ztools and Silo as built-in addons while maintaining cl
├─────────────────────────────────────────────────────────────┤
│ Layer 5: Kindred Addons (mods/) │
│ ┌──────────────────┐ ┌──────────────────┐ │
│ Silo │ │ Gears │
│ │ Open/Save/Commit│ │ Parametric gear
│ │ Part numbering generation │
│ │ Revision control│ │ │
│ BOM management │ │ │
│ └──────────────────┘ └──────────────────┘ │
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
│ │ Silo │ │ Gears Datums │ │ Solver
│ │ PLM/VCS │ │ Gear gen │ │ Datum │ │ Assembly │
│ │ BOM mgmt │ │ │ │ creator │ │ research │
└──────────┘ └──────────┘ └──────────┘ └──────────┘
├─────────────────────────────────────────────────────────────┤
│ Layer 4: Kindred Addon SDK (mods/sdk/) │
│ ┌─────────────────────────────────────────────────────────┐│
@@ -58,7 +57,7 @@ FreeCAD's fundamental data structures: `PartDesign::Body`, `PartDesign::Pocket`,
### Layer 2: FreeCAD Python API -- use as-is
The Python API provides everything needed for feature creation, command registration, and geometry access. ZTools and Silo operate entirely through this layer. Stable FreeCAD APIs (`Gui.addCommand()`, `Gui.addWorkbench()`, `Gui.addWorkbenchManipulator()`) are called directly they do not need SDK wrappers.
The Python API provides everything needed for feature creation, command registration, and geometry access. Addons operate through this layer. Stable FreeCAD APIs (`Gui.addCommand()`, `Gui.addWorkbench()`, `Gui.addWorkbenchManipulator()`) are called directly -- they do not need SDK wrappers.
### Layer 3: Kindred Create Module -- `src/Mod/Create/`
@@ -67,9 +66,9 @@ The Create module serves two roles:
**Python bootstrap** (`Init.py`, `InitGui.py`, `addon_loader.py`):
- Scans `mods/` for `package.xml` manifests with `<kindred>` extensions
- Validates version compatibility, resolves dependencies via topological sort
- Loads addons in priority order (sdk → ztools → silo)
- Loads addons in priority order (sdk → solver → gears → datums → silo)
- Populates `FreeCAD.KindredAddons` registry for runtime introspection
- Sets up deferred Silo dock panels, origin registration, and update checker
- Sets up deferred .kc format registration and update checker
**C++ module scaffold** (`App/`, `Gui/`, `CreateGlobal.h`):
- `CreateApp.so` and `CreateGui.so` shared libraries
@@ -91,7 +90,7 @@ The SDK is loaded first (priority 0) and has no dependencies.
### Layer 5: Kindred Addons -- `mods/`
Pure Python addons with `package.xml` manifests. Self-contained with `Init.py`, `InitGui.py`, and `<kindred>` metadata. Developed and versioned independently as git submodules. Must declare `<dependency>sdk</dependency>` to use SDK APIs. Current addons: **silo** (PLM), **gears** (parametric gear generation).
Pure Python addons with `package.xml` manifests. Self-contained with `Init.py`, `InitGui.py`, and `<kindred>` metadata. Developed and versioned independently as git submodules. Must declare `<dependency>sdk</dependency>` to use SDK APIs. Current addons: **solver** (assembly research), **gears** (parametric gear generation), **datums** (unified datum creator), **silo** (PLM).
---
@@ -158,9 +157,9 @@ Theme colors are now centralized in the SDK's YAML palette (`mods/sdk/kindred_sd
### Phase 6: Build system integration -- DONE
**Goal:** CMake install rules for `mods/` submodules so packages include ztools, Silo, and SDK automatically.
**Goal:** CMake install rules for `mods/` submodules so packages include all addons automatically.
**Implementation:** `src/Mod/Create/CMakeLists.txt` includes install rules for all addons (`mods/ztools`, `mods/silo`, `mods/sdk`) and the C++ module scaffold (`App/`, `Gui/`). Build-time code generation: `version.py.in``version.py` via `configure_file()`.
**Implementation:** `src/Mod/Create/CMakeLists.txt` includes install rules for all addons (`mods/sdk`, `mods/solver`, `mods/gears`, `mods/datums`, `mods/silo`) and the C++ module scaffold (`App/`, `Gui/`). Build-time code generation: `version.py.in``version.py` via `configure_file()`.
**CI/CD status:** Release workflows (`.gitea/workflows/release.yml`) build for Linux (AppImage + .deb), macOS (DMG for Intel + Apple Silicon), and Windows (.exe NSIS installer + .7z archive). Builds run on public runners in dockerized mode. Releases are triggered by `v*` tags. See `docs/CI_CD.md` for details.