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..c55335e3 --- /dev/null +++ b/docs/architecture.rst @@ -0,0 +1,16 @@ +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. + +.. _interactive architecture map: architecture/architecture.html +.. _structured architecture data: architecture/architecture.json + +For the narrative overview, see the repository-level `ARCHITECTURE.md`_ file. + +.. _ARCHITECTURE.md: https://github.com/blues/note-c/blob/master/ARCHITECTURE.md 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..7e999133 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -8,6 +8,17 @@ 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 :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. + +.. _interactive architecture map: architecture/architecture.html +.. _structured architecture data: architecture/architecture.json + .. toctree:: :maxdepth: 1 @@ -16,3 +27,4 @@ note-c is the official C library for communicating with a `Blues Notecard