docs: README rework + small docs-site polish#36
Merged
Conversation
Three small docs-site changes to land alongside the README rework: - Remove repo_url / repo_name / edit_uri from mkdocs.yml so the header's GitHub repo widget no longer renders. Material's search box slides into that right-edge slot automatically. Dead CSS rules in extra.css (source-widget animation disable + light-theme source color) are dropped at the same time. - Footer GitHub icon links to the LunarCommand org root rather than the openarmature-python repo specifically — the org is the right landing for someone exploring the project from the docs footer. - Force flex-row layout on the footer meta inner so the copyright text and social icons stay on one line at all viewport widths (Material's default stacks them at narrow widths). Copyright text shortened to "©OpenArmature 2026" to make sure it fits the same line as the icon on mobile.
Replace the minimal install/quick-example shape with a landing README modeled on pydantic-ai's structure. New sections, in order: - Header with badges (CI, PyPI, spec version, Python versions, license) — the spec badge reads tool.openarmature.spec_version from pyproject.toml on main via Shields.io's dynamic TOML endpoint, so the badge auto-updates when the spec pin moves. - Documentation pointer to openarmature.ai. - Hero copy: workflow framework framing; the graph engine is content-agnostic so the same primitives drive ETL and agents. - Install: uv add + pip install, core + [otel] extras. - Why OpenArmature: nine bullets in framework-author voice covering frozen state, schema-validated merges, per-field reducer policy, subgraph projection seams, compile-time topology (six categories), content-agnostic engine, determinism contract, synchronous checkpoints, TracerProvider isolation. - Hello World: three-node classification pipeline showing three reducer policies on one state class, conditional routing as a pure state function, and an observer (no LLM setup needed). - Next steps: Quickstart / Concepts / Model Providers / API reference / Examples / Spec links to openarmature.ai pages. Drafted on the discuss-readme-rework coord thread; spec-side sign-off on file 03 of that thread.
Six changes after the first pass: - Title capitalized: "openarmature" → "OpenArmature". - PyPI badge explicit blue color. - Python versions badge swapped from pypi/pyversions (which read empty because pyproject.toml has no Python classifiers, so it rendered "missing") to python/required-version-toml, which reads requires-python directly. Renders "python: >=3.12". A separate followup will add the classifiers list to pyproject.toml so the PyPI listing itself shows Python compat. - Hero tagline pulled into a centered h3 above the paragraph so it reads as the headline of the page. - "Why" bullets reformatted: bold header on its own line via <br>, body underneath, instead of inline header-then-body. - Hello World preamble rewritten with more energy: leads with "Forty lines that show the engine in action" and ends with "Copy it, run it, watch the events fire." - All em dashes scrubbed from the copy (eleven total) and replaced with commas, colons, or sentence splits. Next steps switched to "Label: body. [link]" format with colon + period.
There was a problem hiding this comment.
Pull request overview
This PR updates the project’s public-facing documentation and MkDocs site polish after the Phase A docs launch, including a full README restructure and small theme/footer tweaks in the docs site configuration.
Changes:
- Reworks
README.mdinto a “landing page” style README with badges, rationale bullets, and a more representative “Hello World” example. - Removes the MkDocs header repo widget and retargets the footer GitHub icon to the LunarCommand org.
- Adjusts docs CSS to keep the footer meta row on a single line on mobile and removes now-dead CSS for the removed header widget.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| README.md | New landing-style README content, including a more advanced example and updated links/badges. |
| mkdocs.yml | Removes repo widget config; updates copyright text and footer GitHub link target. |
| docs/stylesheets/extra.css | Footer meta layout adjustments for mobile; removes CSS tied to the removed repo widget. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
CoPilot review on PR #36 caught the snippet running invoke() inside asyncio.run() without awaiting drain(). The CompiledGraph.drain docstring says drain is the MUST for short-lived scripts because invoke() returns before the observer delivery queue finishes — the observer's print lines could fail to fire before the process exits, defeating the example's whole purpose. The repo's own observer demo (examples/04-observer-hooks/main.py) already uses the right pattern: async def main() that awaits invoke() and then awaits drain() in a try/finally, then asyncio.run(main()). Match that here. Also drops the unused ``final =`` assignment. Bumps the preamble line count from "forty lines" to "about fifty lines" to match what the snippet actually is.
This was referenced May 13, 2026
chris-colinsky
added a commit
that referenced
this pull request
May 13, 2026
* docs: scrub em dashes, open spec link in a new tab Two small docs-site cleanups bundled in one PR. Em dashes (—) are a common LLM tell; the README scrub during PR #36 replaced them with commas, colons, semicolons, or sentence splits depending on context. Apply the same pass across every page under docs/. Total: 142 em dashes across 13 files, scrubbed without changing the prose's meaning. ``grep -c "—" docs/**/*.md`` returns zero across the tree. Pattern choice per occurrence: parentheticals (X — Y — Z) become parens or commas; definitions (X — body) become ``X: body``; two-clause sentences (X — Y) become sentence splits or semicolons; appositives become commas. Where the em dash was load- bearing in the prose rhythm, the sentence was rewritten rather than mechanically substituted. Also: the apex "specification" link on the docs landing page now opens in a new tab. attr_list is already enabled in mkdocs.yml, so ``{target="_blank" rel="noopener"}`` after the link does the job inline. uv run mkdocs build --strict clean. * docs: drop empty Contributing page The Contributing page was a one-paragraph stub saying "populated as concrete contributor-facing material accrues" — a dead click for any reader who landed on it. Until there's a real contributor pipeline, having no page is more honest than having an empty one. Deletes docs/contributing/ and its nav entry in mkdocs.yml. AGENTS.md remains the agent-facing orientation; if a real contributor doc is wanted later, it can be lifted from AGENTS.md selectively.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Two scopes bundled in one PR — both came out of review after the freshly-shipped Phase A docs site.
README rework
Replaces the minimal install-and-quick-example README with a pydantic-ai-style landing README. Drafted on the `discuss-readme-rework` coord thread; spec-side sign-off on file 03 of that thread.
New structure:
Departures from spec's file 01 draft that landed:
Docs-site polish
Three small site improvements landing alongside:
Test plan
Followup tracked separately
Add `classifiers = ["Programming Language :: Python :: 3.12"]` to `pyproject.toml` so the PyPI listing itself shows Python compatibility (helpful for PyPI search). Effective after the next release. Small chore PR; not in scope here.