From b8595911112c4dbe2ea35aa7b6c293a4b7a24d41 Mon Sep 17 00:00:00 2001 From: chris-colinsky Date: Mon, 18 May 2026 17:59:44 -0700 Subject: [PATCH 1/2] docs(site): UX, nav, and reference cleanup First of the docs-phase PRs. - Expand the spec mention on the homepage into a standalone section linking to openarmature.org (was a paragraph reference only). - Drop `navigation` from the homepage `hide:` list so the left nav renders on the landing page. - Make the "OpenArmature" wordmark clickable via a local override of Material's header partial. The homepage variant also suppresses the default wordmark/page-title scroll swap, which read as a render glitch when both texts are identical. - Add Parallel branches to the Concepts nav (proposal 0011 landed without it). - Refresh the Reference index: add openarmature.prompts; note parallel-branches, multimodal/structured output, and the state-migration registry on existing entries; drop the boilerplate trailer about underscored symbols. --- docs/index.md | 13 ++-- docs/overrides/partials/header.html | 94 +++++++++++++++++++++++++++++ docs/reference/index.md | 15 +++-- docs/stylesheets/extra.css | 32 +++++++++- mkdocs.yml | 6 ++ 5 files changed, 146 insertions(+), 14 deletions(-) create mode 100644 docs/overrides/partials/header.html diff --git a/docs/index.md b/docs/index.md index 2312ff5..844e1e0 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,6 +1,5 @@ --- hide: - - navigation - toc --- @@ -65,7 +64,11 @@ buy-in from every node. --- -Built around an open, language-agnostic -[specification](https://github.com/LunarCommand/openarmature-spec){target="_blank" rel="noopener"}. -A TypeScript implementation is on the roadmap; behaviour stays -identical across implementations via spec conformance fixtures. +## Open specification + +openarmature is defined by a public, language-agnostic specification — +not a Python-shaped opinion exported to other languages. Reference +implementations share conformance fixtures, so behavior stays identical +across languages, runtimes, and tooling stacks. + +[Read the spec →](https://openarmature.org){target="_blank" rel="noopener"} diff --git a/docs/overrides/partials/header.html b/docs/overrides/partials/header.html new file mode 100644 index 0000000..6cb38a1 --- /dev/null +++ b/docs/overrides/partials/header.html @@ -0,0 +1,94 @@ +{#- + Local override of material/partials/header.html. + + Sole change vs. the upstream partial: the "site_name" topic in + ``.md-header__title`` is wrapped in an anchor pointing at the site + root, so clicking the visible "OpenArmature" wordmark navigates + home. Upstream's default leaves that topic as a plain ``
`` — + the only header-area link is the icon-style ``md-logo`` button, + which our extra.css hides because we want the wordmark on its own. + + Re-sync this file when bumping mkdocs-material; everything below is + copied verbatim from the upstream partial except the marked ```` + wrap on the site-name topic. +-#} +{% set class = "md-header" %} +{% if "navigation.tabs.sticky" in features %} + {% set class = class ~ " md-header--shadow md-header--lifted" %} +{% elif "navigation.tabs" not in features %} + {% set class = class ~ " md-header--shadow" %} +{% endif %} +
+ + {% if "navigation.tabs.sticky" in features %} + {% if "navigation.tabs" in features %} + {% include "partials/tabs.html" %} + {% endif %} + {% endif %} +
diff --git a/docs/reference/index.md b/docs/reference/index.md index 3dd000b..d84aa95 100644 --- a/docs/reference/index.md +++ b/docs/reference/index.md @@ -3,13 +3,16 @@ Auto-generated from docstrings. Pick a subpackage: - [`openarmature.graph`](graph.md): state, builder, edges, nodes, - projections, fan-out, middleware, observer, reducers, errors. + projections, fan-out, parallel branches, middleware, observer, + reducers, errors. - [`openarmature.llm`](llm.md): Provider Protocol, message + tool - types, the OpenAIProvider, shared error helpers. + types, multimodal content blocks, structured output, the + OpenAIProvider, shared error helpers. +- [`openarmature.prompts`](prompts.md): PromptManager, PromptBackend + Protocol, FilesystemPromptBackend, PromptGroup, prompt + observability propagation. - [`openarmature.checkpoint`](checkpoint.md): Checkpointer Protocol, - CheckpointRecord, in-memory + SQLite backends. + CheckpointRecord, in-memory + SQLite backends, state-migration + registry. - [`openarmature.observability`](observability.md): correlation primitives and the optional OTel mapping (`[otel]` extra). - -Public surface is what each subpackage's `__init__.py` re-exports. Symbols -prefixed with `_` are package-private and not shown here. diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css index e5bcfc9..eacacc1 100644 --- a/docs/stylesheets/extra.css +++ b/docs/stylesheets/extra.css @@ -157,13 +157,39 @@ color: #cd8bf4; } -/* Hide the default Material book-icon logo next to the site name; the - * "OpenArmature" wordmark stands on its own and already links to the - * site root. */ +/* Hide the default Material book-icon logo next to the site name. The + * "OpenArmature" wordmark itself is made clickable by the local + * ``docs/overrides/partials/header.html`` override, which wraps the + * site-name topic in an ```` pointing at the site root. */ .md-header__button.md-logo { display: none; } +/* Inherit header text colors on the wordmark anchor introduced by the + * partial override, so it reads as the wordmark rather than a styled + * link. */ +.md-header__topic-link, +.md-header__topic-link:hover, +.md-header__topic-link:focus, +.md-header__topic-link:visited { + color: inherit; + text-decoration: none; +} + +/* Suppress the wordmark/page-title scroll animation on the homepage. + * The homepage's page title is also "OpenArmature", so Material's + * default swap flips between the bold wordmark and the un-bold + * page-title of the same text — reads as a render glitch. The + * ``--pinned`` modifier is added by the partial override when + * ``page.is_homepage`` is true, and we don't render the second topic + * at all in that case; this rule keeps the wordmark visible regardless + * of the ``data-md-state="topic"`` toggle Material adds on scroll. */ +.md-header__title--pinned .md-header__topic { + opacity: 1; + pointer-events: auto; + transform: none; +} + /* Hide Material's auto-generated site-name header at the top of the * primary sidebar — we have an explicit ``OpenArmature: index.md`` * entry in the nav config which serves as the home link. */ diff --git a/mkdocs.yml b/mkdocs.yml index 702d8e0..2a4b3fc 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -9,6 +9,11 @@ dev_addr: "127.0.0.1:8765" theme: name: material + # Override directory for theme partials. ``docs/overrides/`` carries + # the customized ``partials/header.html`` that makes the + # "OpenArmature" wordmark clickable (Material's default leaves it + # as a plain ``
``). + custom_dir: docs/overrides palette: - media: "(prefers-color-scheme: light)" scheme: default @@ -94,6 +99,7 @@ nav: - Graphs: concepts/graphs.md - Composition: concepts/composition.md - Fan-out: concepts/fan-out.md + - Parallel branches: concepts/parallel-branches.md - LLMs: concepts/llms.md - Prompts: concepts/prompts.md - Observability: concepts/observability.md From c02dc3cadab985b5849e837430a292c283785f70 Mon Sep 17 00:00:00 2001 From: chris-colinsky Date: Mon, 18 May 2026 18:14:17 -0700 Subject: [PATCH 2/2] docs(site): apply PR review fixes - Header partial override: enumerate both local modifications in the top comment (was written when only the anchor wrap existed and not updated when the homepage pinning logic was added). Resync-on-bump guidance is the whole point of that comment, so it needs to list everything that must be preserved. - Homepage spec section: capitalize "OpenArmature" to match the page H1 and README convention; reserve the lowercase form for code spans referring to the Python package. Replace the em dash on the same line with a comma. --- docs/index.md | 2 +- docs/overrides/partials/header.html | 27 ++++++++++++++++++--------- 2 files changed, 19 insertions(+), 10 deletions(-) diff --git a/docs/index.md b/docs/index.md index 844e1e0..03c98eb 100644 --- a/docs/index.md +++ b/docs/index.md @@ -66,7 +66,7 @@ buy-in from every node. ## Open specification -openarmature is defined by a public, language-agnostic specification — +OpenArmature is defined by a public, language-agnostic specification, not a Python-shaped opinion exported to other languages. Reference implementations share conformance fixtures, so behavior stays identical across languages, runtimes, and tooling stacks. diff --git a/docs/overrides/partials/header.html b/docs/overrides/partials/header.html index 6cb38a1..9ce5faf 100644 --- a/docs/overrides/partials/header.html +++ b/docs/overrides/partials/header.html @@ -1,16 +1,25 @@ {#- Local override of material/partials/header.html. - Sole change vs. the upstream partial: the "site_name" topic in - ``.md-header__title`` is wrapped in an anchor pointing at the site - root, so clicking the visible "OpenArmature" wordmark navigates - home. Upstream's default leaves that topic as a plain ``
`` — - the only header-area link is the icon-style ``md-logo`` button, - which our extra.css hides because we want the wordmark on its own. + Local modifications vs. the upstream partial: - Re-sync this file when bumping mkdocs-material; everything below is - copied verbatim from the upstream partial except the marked ```` - wrap on the site-name topic. + 1. The site-name topic in ``.md-header__title`` is rendered as an + ```` (carrying the ``md-header__topic`` class) so the visible + "OpenArmature" wordmark navigates home. Upstream's default leaves + that topic as a plain ``
``; the only header-area link is the + icon-style ``md-logo`` button, which our extra.css hides because + we want the wordmark on its own. + 2. On the homepage (``page.is_homepage``), the ``.md-header__title`` + element gets an extra ``md-header__title--pinned`` class and the + second ``.md-header__topic`` (the page-title topic) is not + rendered. A paired rule in extra.css pins the wordmark in place + regardless of ``data-md-state="topic"`` so the scroll animation + doesn't fire; we omit the page-title topic because on the + homepage it would just be an un-bold copy of "OpenArmature". + + Re-sync this file when bumping mkdocs-material; preserve both + modifications. Everything below is otherwise verbatim from the + upstream partial. -#} {% set class = "md-header" %} {% if "navigation.tabs.sticky" in features %}