From 55d5bf0a929828874cf37312f5b413c3e5ffe007 Mon Sep 17 00:00:00 2001 From: "Zachary J. Fields (OpenClaw)" Date: Fri, 22 May 2026 21:03:44 +0000 Subject: [PATCH 1/4] Publish architecture map in docs site --- docs/CMakeLists.txt | 7 +++++++ docs/architecture.rst | 12 ++++++++++++ docs/architecture/README.md | 1 + docs/index.rst | 10 ++++++++++ 4 files changed, 30 insertions(+) create mode 100644 docs/architecture.rst diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt index 6c73fdd9..e20c6eb9 100644 --- a/docs/CMakeLists.txt +++ b/docs/CMakeLists.txt @@ -21,6 +21,13 @@ add_custom_target( ${SPHINX_OPTS} ${DOCS_SRC_DIR} ${DOCS_BUILD_DIR} + COMMAND ${CMAKE_COMMAND} -E make_directory ${DOCS_BUILD_DIR}/architecture + COMMAND ${CMAKE_COMMAND} -E copy_if_different + ${DOCS_SRC_DIR}/architecture/architecture.html + ${DOCS_BUILD_DIR}/architecture/architecture.html + COMMAND ${CMAKE_COMMAND} -E copy_if_different + ${DOCS_SRC_DIR}/architecture/architecture.json + ${DOCS_BUILD_DIR}/architecture/architecture.json USES_TERMINAL COMMENT "Running Sphinx HTML build..." ) diff --git a/docs/architecture.rst b/docs/architecture.rst new file mode 100644 index 00000000..140d0700 --- /dev/null +++ b/docs/architecture.rst @@ -0,0 +1,12 @@ +Architecture +============ + +The note-c architecture documentation is maintained with the repository so +module boundaries, public contracts, runtime flow, and update triggers stay +visible as the SDK evolves. + +Open the `interactive architecture map `_ for +the visual graph, or inspect the `structured architecture data +`_ used to generate the map. + +For the narrative overview, see the repository-level ``ARCHITECTURE.md`` file. diff --git a/docs/architecture/README.md b/docs/architecture/README.md index fa41e7a4..fabc86c5 100644 --- a/docs/architecture/README.md +++ b/docs/architecture/README.md @@ -24,6 +24,7 @@ After code changes: - `architecture.html`: single-file visual map for humans. It embeds data from `architecture.json` so it can be opened directly from disk. - `architecture.json`: structured map for AI agents and tooling. - `embed-architecture-json.mjs`: refreshes the embedded JSON block in `architecture.html` from `architecture.json`. +- `../architecture.rst`: Sphinx documentation page that links to the published architecture map and JSON artifact. - `decisions/*.md`: architecture decision records. - `templates/repo-architecture.md`: template for future architecture docs. - `../../AGENTS.md`, `../../CLAUDE.md`, `../../GEMINI.md`, `../../.github/copilot-instructions.md`, and `../../.cursor/rules/architecture-docs.mdc`: AI entrypoints that point future tools back to these docs. diff --git a/docs/index.rst b/docs/index.rst index 0912ee7a..cdb6409d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -8,6 +8,15 @@ note-c note-c is the official C library for communicating with a `Blues Notecard `_. The source code is open source and `available on GitHub `_ under the MIT license. +Architecture +------------ + +Use the `architecture overview `_ to understand note-c's +module boundaries, public contracts, runtime flow, and update triggers. The +overview links to the `interactive architecture map +`_ and the `structured architecture data +`_ used to render it. + .. toctree:: :maxdepth: 1 @@ -16,3 +25,4 @@ note-c is the official C library for communicating with a `Blues Notecard Date: Sat, 23 May 2026 12:54:28 +0000 Subject: [PATCH 2/4] docs: fix architecture rst link wrapping --- docs/architecture.rst | 8 +++++--- docs/index.rst | 8 +++++--- 2 files changed, 10 insertions(+), 6 deletions(-) diff --git a/docs/architecture.rst b/docs/architecture.rst index 140d0700..fd701bc0 100644 --- a/docs/architecture.rst +++ b/docs/architecture.rst @@ -5,8 +5,10 @@ The note-c architecture documentation is maintained with the repository so module boundaries, public contracts, runtime flow, and update triggers stay visible as the SDK evolves. -Open the `interactive architecture map `_ for -the visual graph, or inspect the `structured architecture data -`_ used to generate the map. +Open the `interactive architecture map`_ for the visual graph, or inspect the +`structured architecture data`_ used to generate the map. + +.. _interactive architecture map: architecture/architecture.html +.. _structured architecture data: architecture/architecture.json For the narrative overview, see the repository-level ``ARCHITECTURE.md`` file. diff --git a/docs/index.rst b/docs/index.rst index cdb6409d..ad187c08 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -13,9 +13,11 @@ Architecture Use the `architecture overview `_ to understand note-c's module boundaries, public contracts, runtime flow, and update triggers. The -overview links to the `interactive architecture map -`_ and the `structured architecture data -`_ used to render it. +overview links to the `interactive architecture map`_ and the +`structured architecture data`_ used to render it. + +.. _interactive architecture map: architecture/architecture.html +.. _structured architecture data: architecture/architecture.json .. toctree:: :maxdepth: 1 From ff3cc78fe64d7ceff2ed200a0b0313cfb0359e58 Mon Sep 17 00:00:00 2001 From: "Zachary J. Fields (OpenClaw)" Date: Sat, 23 May 2026 13:21:23 +0000 Subject: [PATCH 3/4] docs: use sphinx doc role for architecture link --- docs/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.rst b/docs/index.rst index ad187c08..7e999133 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -11,7 +11,7 @@ note-c is the official C library for communicating with a `Blues Notecard `_ to understand note-c's +Use the :doc:`architecture overview ` to understand note-c's module boundaries, public contracts, runtime flow, and update triggers. The overview links to the `interactive architecture map`_ and the `structured architecture data`_ used to render it. From b8b71872af9fe0c529b05f10b12416adf7b36e54 Mon Sep 17 00:00:00 2001 From: "Zachary J. Fields (OpenClaw)" Date: Sat, 23 May 2026 13:29:02 +0000 Subject: [PATCH 4/4] docs: link architecture overview from sphinx --- docs/architecture.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/architecture.rst b/docs/architecture.rst index fd701bc0..c55335e3 100644 --- a/docs/architecture.rst +++ b/docs/architecture.rst @@ -11,4 +11,6 @@ Open the `interactive architecture map`_ for the visual graph, or inspect the .. _interactive architecture map: architecture/architecture.html .. _structured architecture data: architecture/architecture.json -For the narrative overview, see the repository-level ``ARCHITECTURE.md`` file. +For the narrative overview, see the repository-level `ARCHITECTURE.md`_ file. + +.. _ARCHITECTURE.md: https://github.com/blues/note-c/blob/master/ARCHITECTURE.md