Skip to content

Documentation

Myna documentation is split between root project files, MkDocs site pages, generated API docs, examples, and agent-facing orientation files.

Documentation Surfaces

Surface Purpose
README.md User-facing project overview, installation, citation, and high-level usage
ARCHITECTURE.md Repository architecture, boundaries, control flow, and extension points
AGENTS.md Short entrypoint and checklist for coding agents
CONTRIBUTING.md Contributor workflow, branch names, commit convention, and PR title format
docs/ MkDocs source pages for user/developer documentation
docs/api-docs/ Generated API documentation, ignored by git
examples/README.md and nested readmes Example organization and dependency notes
CHANGELOG.md User-visible release and unreleased change history

Docs Toolchain

The docs site uses MkDocs Material. Configuration is in mkdocs.yml; navigation is managed by docs/.pages through the Awesome Pages plugins.

API docs are generated by:

uv run scripts/group_docs.py

That script regenerates docs/api-docs/ with LazyDocs and writes nested .pages files. The generated API docs are ignored by git. Run the script before strict docs builds when you need parity with CI.

CI generates docs with Python 3.10. If LazyDocs fails in a newer local Python environment while generating docs/api-docs/, use a Python 3.10 development environment before treating strict MkDocs failures as docs-content failures.

Build the docs with:

uv run mkdocs build --strict

What To Update

Change type Update
Install, CLI usage, or public workflow behavior README.md, docs/getting_started.md, and relevant example docs
Component, file, metadata, database, or app extension pattern docs/developer_guide.md and possibly ARCHITECTURE.md
Test markers, CI commands, external-app checks docs/testing.md
Docs tooling, navigation, generated API docs, or harness checks This page and AGENTS.md if agents need to know
Subsystem boundary, control flow, dependency model, or extension point ARCHITECTURE.md
User-visible change CHANGELOG.md under ## Unreleased

Use root files for repository-wide orientation and MkDocs pages for user/developer guides. Avoid duplicating long sections between README.md, AGENTS.md, and ARCHITECTURE.md.

Agent Harness

The documentation harness is intentionally small:

  • AGENTS.md is the compact entrypoint.
  • ARCHITECTURE.md is the higher-detail system map.
  • docs/testing.md and this page cover validation and maintenance details.
  • scripts/check_dev_tools.py verifies that the current shell can run the repository's development toolchain.
  • scripts/check_docs_harness.py verifies required headings, required AGENTS.md links, relative link targets, and the compact size of AGENTS.md.

Run the harness check with:

uv run python scripts/check_docs_harness.py

The check runs in pre-commit and main CI. If it fails, follow the error message: it should identify the missing file, heading, link target, or size limit.