Nexus documentation-system architecture and delivery plan¶

Organize maintained contracts, public APIs, usage guidance and evidence into task-oriented, versioned, independently obtainable offline documentation. Reuse Markdown/public headers with Sphinx, Doxygen and Breathe, adding MyST. Product code/policy stays external.

The site, CLI, locks, prose, translations and diagram set implement this plan. Actual build/publication/recovery follows the 58-item implementation ledger and execution evidence; the migration mapping records destinations/retention. This document changes no platform support, software qualification or physical status. New/changed docs follow content/diagram standards and templates. The complete checklist derives from that ledger; diagrams distinguish current/target views.

1. 目标和边界¶

Help application developers use the platform correctly first, integrators extend it second, and maintainers/reviewers assess changes/evidence third. Readers complete definite tasks without traversing implementation history first.

Applications use current static instances, typed factories and C polymorphic interfaces.
One authored TOML is the default configuration; maintained JSON supplies SoC/Board facts.
Integration guidance retains context, deadlines, borrowing, draining and recovery.
Production support, software tests, ARM links, candidates and HIL are separate.
Documents, source, configuration and qualified baselines have explicit identities.
Maintain authoritative contracts once; other pages link/include/derive them.
Links/search/offline packages cover current prose; history has visible boundaries.

Docs create no product apps/tasks/private PCBs/Flash partitions/secure-update/recovery policy. Tutorials pin X-Gen-Lab/nexus-examples; platform source keeps only common fixtures/validation code. Publication does not promote models/linking into hardware qualification.

2. 首页从读者任务进入¶

Reader	Home-page path	Outcome
Application developer	Pin source → use SDK → choose Board/OS → configure instances → factory lookup → I/O → shutdown.	A buildable external project with correct resource lifecycles.
Platform integrator	New Board → SoC/provider → reusable device/component → model/ARM/HIL.	An integration slice with explicit scope, resources and validation.
Maintainer	Pin source → install tools → TDD → review → dependency upgrades → SDK/docs delivery.	Traceable changes and recoverable delivery.
Acceptance reviewer	Support matrix → exact configuration → software records → candidate → physical status.	Qualification judgments for exact baselines.
Legacy user	Configuration migration → interface migration → ownership changes → revalidation.	A new consumer independent of old APIs.

Tutorials follow one verified path; how-to guides solve one goal; references give exact rules; explanations describe principles/tradeoffs. Keep home sidebars two levels deep, using domain indexes for complexity. Search excludes historical tutorials/large raw evidence by default and labels version, page category, actual prose language and translation state. Summaries prioritize tasks/technical content, with source/qualification shown separately so repeated disclaimers do not dominate. First operations reference pinned source/recursive dependencies; never assume GitHub branches match the documentation version.

3. 内容权威和派生关系¶

Content	Authority	Site handling
Public declarations and individual API contracts	Public headers in core/arch/io/os/components.	Generated Doxygen/Breathe; guides link symbols.
CPU/chip/route/Board facts	SoC/Board JSON, production resolver and source review.	Reuse capability derivation with explicit human-written limitations.
Cross-API lifecycles/execution order	Current system-contract prose.	Include directly; tutorials do not define norms retroactively.
Configuration syntax/rejections	Production resolver, typed IR and contracts.	Actually parse complete examples; label fragments.
Engineering/style requirements	AGENTS, existing style files and engineering contracts.	Preserve rules and connect actionable procedures.
Implementation support	Production implementation/selection, reviewed facts and explicit boundaries.	One authoritative support entry; others summarize/link.
Executed qualification	Exact-source result indexes and raw receipts.	Show scope, configuration, tools and artifact identity.
Plans/exit conditions	Domain CSV ledgers.	Derived task views, not duplicate status databases.
File organization/maintenance map	Source-adjacent READMEs.	Retain local entries; include/version-link public portions.
Historical designs/counts	docs/archive	Separate historical entries establish no current qualification.

Chip capability, implemented modes, authorized Board wiring, software execution and HIL passes are distinct facts. Derived tables consume existing authorities without new capability/qualification rules. CSV implemented does not automatically become accepted. Overlapping ledgers cannot sum into completion percentages. Preserve original IDs, exit conditions and failed attempts.

4. 目标目录与渐进接入¶

docs/
├── index.md                      任务入口、版本与资格边界
├── tutorials/                    首次完成一个可验证流程
├── guides/                       使用、接入、取消/排空、故障处理
├── reference/
│   ├── api/                      Core/Arch/I/O/OS/Components
│   ├── configuration/            TOML、facts、IR、预算、CLI
│   ├── platforms/                CPU/SoC/Board 精确支持切片
│   └── contracts/                当前有效系统合同
├── explanation/                  架构、factory、所有权、资源和取舍
├── status/                       支持、当前资格、HIL、发布、台账视图
├── development/                  风格、TDD、评审、依赖与文档维护
├── design/                       活跃方案、决策和原始专项台账
├── delivery/                     保留原路径的执行记录与结果索引
├── locale/                       gettext/PO 翻译
├── assets/                       本地图片、图源和样式
├── sphinx/                       迁移期配置与 API/RST 包装页
└── archive/                      历史资料，不进入默认站点搜索

First change the source root to docs/, retaining docs/sphinx/conf.py during migration. MyST makes design/delivery Markdown navigable/searchable pages. Integrate prose/fix entries before moving mutable content by mapping; do not move everything before repairing references.

toctree is the sole navigation composition; READMEs are repository entry points. Initially navigate existing paths, then retain stable page IDs with a small redirect table. Resolve links by actual source location and check every reference/explicit anchor on moves. Review reorganization separately from normative changes.

Retain original source paths for:

Three existing delivery-results JSON indexes and execution records.
Six original domain CSV ledgers and this documentation-system ledger.
Original archive content, IDs and historical qualification.
Tool-input contracts until references/gates migrate together successfully.

Status pages reference/derive these sources without rewriting receipts. External archives preserve original bytes/member locations. New paths do not fabricate old-source execution or change archive identity.

5. 技术选择¶

Decision	Choice/rationale
Site	Reuse Sphinx with existing strict CI/C API cross-references.
Prose	Markdown/MyST; keep RST for API directives/transition pages.
API	Public-only Doxygen XML + Breathe; preserve comment style.
Translation	One canonical source plus Sphinx gettext/PO; one translation chain.
Navigation	toctree/module indexes; no independent content database.
Status	Reuse capability derivation, result indexes, CSV and identity tools.
Theme	Retain current theme first; evaluate separately after content/search acceptance.
Diagrams	Editable DOT + local SVG with locked Graphviz; Sphinx graphviz may be used.
Delivery	Relative-link HTML packages/manifests without CDNs.

No switch to MkDocs/Docusaurus or extra frontend runtime for basic navigation. Evaluate extensions against real failing examples when MyST/Sphinx is insufficient. Do not maintain a second contents/capabilities table or universal snippet DSL per document.

Exclude archives, generated Doxygen, _build, raw logs, large archives and fixture outputs. Status pages provide readable summaries/download indexes rather than indexing all evidence. Source-adjacent READMEs are not copied contracts; inclusion verifies relocated links. Other source links bind the site Git revision, avoiding moving development branches.

6. 页面和 API 组织¶

New public pages use standard MyST front matter with a few maintained fields:

id: guides.cancel-and-drain
type: how-to
audience: consumer
source_language: zh_CN

id identifies pages/migration but does not automatically create MyST anchors. Public anchors use explicit targets/Sphinx labels retained and actually built after path changes; redirects handle old URLs without another reference framework. Derive versions, updates, source links and validation from Git/execution inputs rather than handwritten timestamps/copied hashes. Add legacy metadata in batches without defaults fabricating language or qualification.

Page type	Required content
tutorial	Goals, exact prerequisites, pinned configuration, complete steps, expectations and cleanup.
how-to	One task, contexts, minimum steps, failure handling and scope.
reference	Fields/symbols, ranges, units, rejections and authority.
explanation	Problems, mechanisms, tradeoffs/boundaries and linked normative contracts.
status	source/config/scope, actual execution and evidence locations.

Replace one aggregate doxygenindex with Core/Arch/I/O/OS/Components entries. Device pages link contracts/call order before generated symbols. Do not hand-copy declarations.

Explain factories separately: lookups return generated static objects; ordinary I/O calls providers directly through faces. Examples use actual nexus_factory.h. Default IDs, strong IDs and optional capabilities each bind exact configuration/execution. Public headers and assembly-generated interfaces are not one platform-wide invariant API.

7. 双语与图示¶

This is target design, not implementation evidence. Arrows carry inputs/artifacts; software/HIL records are read-only and documentation builds establish no platform qualification. See FIG-12 for sources/details.

Each page has one canonical source declaring its original language. Every current page provides complete English and Chinese prose; Chinese originals generate English through the same gettext chain. Mixed contracts may use reviewed source-language catalogs to translate their other-language passages without duplicating canonical contracts. API identifiers, keys, error codes, CSV/JSON and raw logs retain original bytes or meaning.

gettext/PO is the sole translation chain. Review binds source versions; after source changes, affected translations become stale/fuzzy rather than appearing complete because locale builds pass. Only reviewed/stale/missing/original states exist, derived per page and visible.

Use both Chinese/English originals to test en/zh_CN round-trips, missing fallback and stale/fuzzy states. Actual prose language/review state determines labels; build locales cannot override them.

Visible normative prose on every current page requires independent semantic review with no unresolved fuzzy entries. Fast checks validate source digests/review markers; strict builds also require the fresh complete message set. Missing/stale translations fail. Previews truthfully show actual language/gaps. Archives retain original translation/qualification scope.

Keep reviewable diagram sources and local outputs without online Mermaid/CDNs/external fonts/scripts. New renderers need locks/actual validation; arrows, lifecycles and support scope are reviewed with prose. Offline checks cover images/search/navigation/bilingual entries, not home pages alone. Content/diagram standards define all fifteen classes and visual/source/failure rules.

8. 示例与文档门禁¶

Prefer literalinclude from real fixtures or pinned external examples instead of unbuildable handwritten copies. Complete tutorials actually consume current source SDKs. Hardware commands state tools/Boards/connections; normal builds never flash or access devices. Fetch/pin external revision/hash/license inputs beforehand; Sphinx reads them without fetching latest or running external scripts.

Full TOML uses production resolvers. Board/CPU JSON follows actual integration paths, not syntax-only checks. Explained fragments retain syntax checks without complete-configuration qualification. Keep nexus-toml-fragment conventions.

Only explicitly reviewed fixtures execute maintained shell/CMake flows; never extract/run arbitrary Markdown commands. Complete fragments, illustrations and execution reports state separate scopes.

Layer	Validation	Trigger
Fast source checks	Formatting, metadata, page IDs, local files/anchors and reachability.	commit/CI
Configuration examples	Actual complete TOML/JSON resolvers and fragment rationale.	Relevant changes at commit/CI.
Executable examples	Real Native/ARM/SDK consumers and failure paths.	Relevant behavior changes in CI.
Public API	Existing comment contracts + strict Doxygen/Breathe.	API/docs CI.
Whole site	Strict MyST/Sphinx references, navigation, search, translation status and resources.	CI/publication.
External links	Bounded timeout/retry; distinguish 404 from network failure.	Periodic/publication.
Post-publication	Actual site identity, critical pages, legacy URLs, resources/downloads.	After actual deployment.

Commit checks default offline without rerunning complete firmware qualification. New doc tools/gates use actual Python unittest RED→GREEN; C behavior tests use GoogleTest/GoogleMock and examples use existing real builds. Prose changes run applicable checks, without implementation-mirroring tests.

9. 一个工具入口¶

Unified entry below; tool installation/acceptance is in the maintenance guide:

python tools/dev/dev.py docs check
python tools/dev/dev.py docs test
python tools/dev/dev.py docs build --language zh_CN
python tools/dev/dev.py docs build --language en
python tools/dev/dev.py docs preview
python tools/dev/dev.py docs package
python tools/dev/dev.py doctor --target docs

dev.py stays a thin route; docs reuse process runners, timeouts, exits and identity. docs.py/.sh/.ps1/.bat forward or state migration rather than maintaining separate generation.

check validates maintained sources/configuration examples without platform qualification.
build runs Doxygen/Sphinx in fresh outputs with -n -W –keep-going.
preview serves successful outputs without implicit installation/dependency replacement.
package verifies success/identity and seals outputs, without publishing products/platforms automatically.
doctor distinguishes absent tools, wrong versions and unexecuted qualification.

Preserve actual exits, diagnostics and logs. Ownership-controlled outputs cannot overwrite inputs. Old XML/HTML never substitutes for fresh success. Isolate repeated outputs/translation caches. Inject this build’s Breathe XML path rather than reading old docs/api results.

Python dependencies/wheel hashes form a separate closure, initially the executed Linux x86_64 Python tuple. Doxygen version/bytes are pinned. HAVE_DOT=NO does not mean the docs chain lacks Graphviz; pin rendering Graphviz/actual fonts too. Execute require-hashes installation in clean environments; lock files alone prove no installation. Other hosts qualify separately.

10. 版本和发布身份¶

Documentation manifests reuse existing identity and evidence-location structures. The table maps actual schema-1 fields only; the single delivery contract and production packager define the complete format:

Field	Origin/meaning
`version`	Existing platform policy checked against CMake, not another constant.
`code_source.commit`、`code_source.tree`	Actual code described.
`documentation_source.commit`、`documentation_source.tree`	Source for this prose, configuration and translation build.
`qualified_code.commit`、`qualified_code.tree`	Exact referenced qualification source, retaining its original scope.
`qualified_code.index`、`qualified_code.index_sha256`	Existing results-index path and digest, retaining configuration and execution identity.
`tool_versions`	Actual tools, installation receipts and dependency-lock identities; version strings do not establish execution.
`languages`	Actually built locale array; per-page translation-review states are recorded in build results.
`files`	Successful payload `path`, `bytes` and `sha256`; exclude manifest/checksums/archive/outer receipts.

The three source identities never overwrite one another. Docs may cite verified older code without labeling its execution as current HEAD. Display described/qualified sources separately where different. This plan began at docs HEAD 7abde0e4 and qualified code cc6a065c; historical SoC records remain independent. New implemented tools execute gates on their new source.

Version URLs follow this structure; actual publication records determine published versions:

/dev/<documentation-commit>/<language>/
/versions/<release-id>/<language>/
/stable/<language>/
/versions/<release-id>/api/

release-id binds one manifest; doc updates with unchanged platform versions still cannot overwrite immutable directories. stable is an accepted software-SDK docs entry, not all-HIL-passed. Truthful unexecuted HIL permits software docs publication without invented physical support.

Initially preview PRs as identified CI artifacts. Trusted deployment consumes verified output without elevated execution of external PR source. Sites/stable become published only after actual deployment; workflows/build success are not public proof. External-link reports bind current inputs and distinguish bad links/network limits. Unverified essential source/standards/download entries prevent delivery passes; optional-reference limitations remain explicit.

Handle legacy /en, /zh_CN and /api individually. Old HAL/OSAL/Kconfig pages point to versioned history/migration rather than silently redirecting same-named functions to different contracts.

11. 离线包、下载和恢复¶

nexus-docs-<release-id>/
├── index.html
├── en/
├── zh_CN/
├── api/
├── downloads/                 小型索引和独立下载说明
├── manifest.json
├── checksums.txt
└── licenses/

Relative HTML/images/search/links need no CDN. Public locations do not depend on original workspace paths; retain receipt paths and provide archive/member retrieval instructions. Publish large evidence separately rather than copying it into sites; unavailable downloads are explicitly local-only.

Manifests bind inputs/payload; checksums cover payload/manifests but not themselves. Outer archive hashes belong in separate receipts, avoiding self-reference. Reuse archive/verifier tools without another candidate state machine. HTML proves docs delivery, not SDK/MCU/HIL. Pages may display source identity but never their self-covering final manifest hash; manifests/checksums are excluded from manifest.files to avoid indirect cycles.

CI artifacts serve previews; long-term publications need stable locations/retention/verification. Actually retrieve/restore in independent roots, browse key pages and verify. Cross-failure-domain recovery depends on real storage; unexecuted work stays incomplete. Normalize removable path/time differences, but actual dual builds establish reproducibility.

12. 实施工作包与排程¶

D1–D6 are categories, not six mandatory sequential periods. Follow ledger dependency DAGs; estimate dates after tooling/content scope is known. DOC-21 terminology and DOC-25 diagram/offline rules precede dependent content. DOC-58 review can run in parallel, but closure waits for all fifteen classes/checks.

Work package	Scope	Delivery/exit conditions
D1	Entry points, authorities and prose rules.	Fix entries/examples/evidence navigation; map every source/retained path.
D2	Site, architecture and API.	MyST/source-root, unique navigation, module APIs and searchable contracts.
D3	Tutorials, integration and execution.	Actual consumers verify SDK/async/integration/shutdown/migration tasks.
D4	Bilingual content, diagrams and reader review.	Critical bilingual pages, states/offline diagrams and task walkthroughs.
D5	Tools, gates and CI.	Unified CLI, gates, locks and actual CI/preview negative paths.
D6	Publication, restoration and migration closure.	Versions/offline packages, actual publication checks and independent restoration.

Establish base rules first; tools/prose run in parallel. Publication depends on successful builds, identities, critical content, translations and complete diagram review. Platform main/version integration is external; this plan cannot imply merge/deployment. Codex owns maintenance; other agents perform required independent reviews.

Each DOC ID records implementation_status, validation_status and exit_condition separately. Do not renumber original ledgers. This documentation ledger differs from the existing 48-item build ledger and conversational 48-item whole-project proposal; that proposal needs its own ledger rather than documentation-completion aggregation.

13. 最终交付检查¶

Completion requires all of:

Explicit authorities for current prose/APIs/support/qualification/history without duplicate norms.
Complete use/integration/maintenance/acceptance paths with required actual configuration/consumer execution.
Reachable/searchable maintained pages, valid references and accurately bounded legacy URLs.
Actual English/Chinese review of every current page, with truthful original/stale/missing previews.
Identical strict local/CI rules with real bad-input/missing-tool failures and diagnostics.
API/factory/TOML/ThreadX/DMA/reference statements match production selection.
Readable/verifiable docs/code/qualification/tool identity and truthful history/HIL.
Clean-environment offline packages browse/verify independently; downloads match actual sites.
Actual publication/restoration results with unestablished host/storage/hardware conditions explicit.
Semantic/visual/offline review of fifteen required plus two supplemental diagrams. Record identity/scope of four historical planned diagrams separately; unclaimed configurations/extensions retain explicit boundaries.