docs: C++ API reference, signal architecture, and build integration #166

forbes · 2026-02-10T14:38:04Z

forbes commented

2026-02-10 14:38:04 +00:00

Summary

Complete C++ developer documentation for the origin system, signal architecture, and Gui module build integration.

New documentation pages (10 commits)

C++ API Reference (closes #130, #131, #132, #133, #134, #135):

docs/src/reference/cpp-file-origin.md — FileOrigin abstract interface
docs/src/reference/cpp-local-file-origin.md — LocalFileOrigin implementation
docs/src/reference/cpp-origin-manager.md — OriginManager singleton
docs/src/reference/cpp-origin-selector-widget.md — OriginSelectorWidget toolbar
docs/src/reference/cpp-command-origin.md — CommandOrigin dispatch
docs/src/reference/cpp-file-origin-python.md — FileOriginPython bridge

Guides (closes #136):

docs/src/reference/cpp-custom-origin-guide.md — Creating a custom origin in C++

Architecture (closes #137):

docs/src/architecture/signal-architecture.md — fastsignals vs Qt signals

Development (closes #138):

docs/src/development/gui-build-integration.md — Gui module build integration

Other changes

Deduplicated silo server content in guide/silo.md, architecture/silo-server.md, reference/configuration.md — replaced with cross-references to authoritative docs/src/silo-server/
Fixed dead link in docs/COMPONENTS.md
Added Kindred addon test suite (tests/test_kindred_pure.py, 78 tests)
Added test-kindred pixi task and CI workflow step
Updated docs/src/SUMMARY.md with all new pages

## Summary Complete C++ developer documentation for the origin system, signal architecture, and Gui module build integration. ### New documentation pages (10 commits) **C++ API Reference** (closes #130, #131, #132, #133, #134, #135): - `docs/src/reference/cpp-file-origin.md` — FileOrigin abstract interface - `docs/src/reference/cpp-local-file-origin.md` — LocalFileOrigin implementation - `docs/src/reference/cpp-origin-manager.md` — OriginManager singleton - `docs/src/reference/cpp-origin-selector-widget.md` — OriginSelectorWidget toolbar - `docs/src/reference/cpp-command-origin.md` — CommandOrigin dispatch - `docs/src/reference/cpp-file-origin-python.md` — FileOriginPython bridge **Guides** (closes #136): - `docs/src/reference/cpp-custom-origin-guide.md` — Creating a custom origin in C++ **Architecture** (closes #137): - `docs/src/architecture/signal-architecture.md` — fastsignals vs Qt signals **Development** (closes #138): - `docs/src/development/gui-build-integration.md` — Gui module build integration ### Other changes - Deduplicated silo server content in `guide/silo.md`, `architecture/silo-server.md`, `reference/configuration.md` — replaced with cross-references to authoritative `docs/src/silo-server/` - Fixed dead link in `docs/COMPONENTS.md` - Added Kindred addon test suite (`tests/test_kindred_pure.py`, 78 tests) - Added `test-kindred` pixi task and CI workflow step - Updated `docs/src/SUMMARY.md` with all new pages

forbes added the documentation label 2026-02-10 14:38:04 +00:00

forbes added 10 commits 2026-02-10 14:38:05 +00:00

docs: add FileOrigin API reference and Kindred addon test suite bdbe1b163a

- Add docs/src/reference/cpp-file-origin.md: full API reference for the
  FileOrigin abstract interface, OriginType/ConnectionState enums,
  LocalFileOrigin behavior, and ownership detection algorithm
- Add SUMMARY.md entry under new 'C++ API Reference' section
- Add tests/test_kindred_pure.py: 78 pure-logic unit tests covering
  update_checker, datum_commands, spreadsheet_commands, silo_commands,
  silo_start, and silo_origin (no FreeCAD binary required)
- Add tests/run_kindred_tests.py: two-tier test runner with CI exit codes
- Add pixi task 'test-kindred' for running addon tests
- Add CI/CD step in build.yml to run addon tests before build

Closes #130

docs(c++): OriginManager singleton API reference 98218661d0

Document the OriginManager singleton: origin registration/unregistration
lifecycle, document-to-origin resolution algorithm (non-local checked
first, local as fallback), explicit vs detected ownership, preference
persistence, signal catalog, and memory model.

Closes #132

docs(c++): CommandOrigin commands (Commit/Pull/Push/Info/BOM) 633bef6b18

Document the five origin commands: activation pattern (ownership lookup
via findOwningOrigin, capability gate check), command table with IDs,
shortcuts, icons and capability gates, eType flags for undo integration,
registration in CreateOriginCommands(), and the full dispatch call chain
from C++ through FileOriginPython bridge to Python SiloOrigin.

Closes #134

docs(c++): FileOriginPython bridge — Python-to-C++ origin adapter c9f6f9e02b

Document the FileOriginPython bridge: registration via
FreeCADGui.addOrigin()/removeOrigin(), method dispatch pattern with GIL
management, callStringMethod/callBoolMethod/callMethod helpers, document
argument marshalling (App::Document* <-> App.Document), enum mapping
tables for OriginType and ConnectionState, required vs optional Python
interface methods with defaults, error handling (never propagates Python
exceptions into C++), icon resolution via BitmapFactory, and lifetime/
ownership model between Py::Object, _instances vector, and
OriginManager unique_ptr.

Closes #135

docs: deduplicate silo server content in favor of silo-server/ authority 77e5063b95

Replace duplicated server setup, deployment, migrations, and config
sections in guide/silo.md, architecture/silo-server.md, and
reference/configuration.md with cross-references to the authoritative
docs/src/silo-server/ directory.

Fix dead link in COMPONENTS.md (mods/silo/docs/ → docs/src/silo-server/).

docs(c++): LocalFileOrigin implementation guide 8fd664d509

Covers ownership-by-exclusion algorithm, document identity, open/save
workflows, capability flags, connection state, OriginManager integration,
and unregister protection.

Closes #131

docs(c++): OriginSelectorWidget toolbar integration c25aa17591

Covers widget lifecycle, signal connections (fastsignals), menu
population, origin selection with authentication gate, icon overlays
for connection state, StdCmdOrigin/OriginSelectorAction command
wrappers, and StdWorkbench toolbar placement.

Closes #133

docs(c++): guide to creating a custom origin in C++ 1561dff860

Step-by-step walkthrough covering class definition, identity methods,
ownership detection with tracking properties, document operations,
capability flags, extended PLM operations, connection lifecycle,
OriginManager registration, and CMake build integration.

Closes #136

docs(arch): signal architecture — fastsignals vs Qt signals 5774f42876

Explains the dual-signal system: fastsignals for domain events
(origin lifecycle, document changes, application state) and Qt signals
for UI framework integration. Covers API, connection patterns
(scoped_connection RAII, DocumentObserver, temporary blocking),
thread safety model, performance, and common mistakes.

Closes #137

docs(dev): Gui module build integration

Build and Test / build (pull_request) Successful in 1h20m55s

Details

779e32e24a

Covers FreeCADGui target definition, dependency chain (fastsignals,
Qt6, Coin3D, PySide6, PyCXX), source file organisation and how to
add new files, theme/stylesheet build-time copying, version constants,
precompiled headers, CMake presets, ccache, and pixi tasks.

Closes #138

forbes added 1 commit 2026-02-10 14:41:33 +00:00

merge: resolve build.yml conflict with main

Build and Test / build (pull_request) Successful in 35m52s

Details

8247127905

Keep Kindred addon test step, drop removed cache-date step.

forbes merged commit 87b23c5aae into main

2026-02-10 14:41:53 +00:00

forbes referenced this issue from a commit

2026-02-10 14:41:55 +00:00

Merge pull request 'docs: C++ API reference, signal architecture, and build integration' (#166) from docs/api-reference into main

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: kindred/create#166