Skip to content

feat: extract configurable executable documentation framework - #6

Merged
softmarshmallow merged 1 commit into
mainfrom
feature/executable-docs-framework
Oct 4, 2026
Merged

softmarshmallow merged 1 commit into
mainfrom
feature/executable-docs-framework

Conversation

@softmarshmallow

Copy link
Copy Markdown
Member

N3's executable documentation harness currently owns document composition and publication inside its application replay. This extracts a reusable Rust SDK and keeps N3's existing published guide byte-for-byte compatible.

Changes

  • Add the unpublished executable-docs SDK for Rust-authored prose, checked observations, frozen resources, typed references, and contributor notes. Reader and Contributor exports reuse one execution.
  • Let adopters configure page/resource paths, baseline roots, audience directories, and relative-path resolution, or integrate directly with their own tests and CLI. No repository discovery or prescribed project topology is required.
  • Share strict artifact ownership, comparison, staged publication, and recovery with N3. Preserve audience isolation, portable inventory paths, and separation from reserved transaction directories.
  • Migrate the hand-tool and navigation narratives into their Rust scenarios while retaining production replay, exact media, and the existing N3 manifest. The remaining 26 guides keep their templates.
  • Add CLI, serde_json, and configured-layout examples, behavioral regressions, API documentation, an architecture contract, and native/CI verification gates.

Validation

  • Clean-commit native just verify through the pre-push hook: formatting, workspace Clippy, tooling, SDK/consumer tests, doctests, strict API docs, N3 tests with exact guide replay, and measurement checks.
  • Final standalone Rust 1.95 copy: 113 SDK tests and four doctests passed. A project with no root Cargo manifest or Git repository produced identical exports after relocation and invocation from unrelated working directories.
  • Final cached pinned Linux environment: 125 SDK/consumer tests and four doctests passed, including case-sensitive filesystem behavior.
  • All 138 existing N3 guide and renderer-baseline files remain unchanged.

The SDK/API and manifest remain experimental and unpublished. Markdown is the current complete exporter; independent developer adoption, alternate publishers, and Git/diff views remain future work. Windows inventory separators are corrected, but Windows runtime validation has not been performed.

@softmarshmallow
softmarshmallow merged commit 82f5011 into main Oct 4, 2026
10 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant