Documentation Guide¶

How the alienbio documentation is organized and our conventions for writing it.

Three Documentation Layers¶

Layer	Purpose	Audience	Depth
User Guide	How to use the system	Users	High-level, tutorial
Architecture Docs	Complete specification	Developers	Comprehensive, conceptual
API Docs	Code reference	Developers	Comprehensive, low-level

                    ┌─────────────────┐
                    │   User Guide    │  ← "How do I use this?"
                    │   (high-level)  │
                    └────────┬────────┘
                             │ links to
                             ▼
                    ┌─────────────────┐
                    │  Architecture   │  ← "How does this work?"
                    │  (comprehensive)│
                    └────────┬────────┘
                             │ links to
                             ▼
                    ┌─────────────────┐
                    │    API Docs     │  ← "What's the signature?"
                    │   (auto-gen)    │
                    └─────────────────┘

User Guide¶

Location: docs/Alienbio User Guide/

Purpose: Get users started quickly with enough context to be productive.

Characteristics: - High-level, tutorial-style - Not comprehensive — covers main concepts, not every detail - Links to Architecture Docs for complete specifications - Examples and patterns

Contents: - Core Spec — Intro to spec language (links to Spec Language Reference) - Execution Guide — CLI, agents, running experiments - Agent Interface — Agent interaction protocol - Generator Spec — Template-based generation

Architecture Docs¶

Location: docs/architecture/

Purpose: Complete, authoritative specification of all components.

Characteristics: - Comprehensive — everything is documented - Conceptual — explains design, not just signatures - Organized by type: classes, modules, commands - Links to API Docs for code-level details

Structure:

architecture/
├── Architecture Docs.md    # root index
├── ABIO Protocols.md       # class index → classes/
├── ABIO Modules.md         # module index → modules/
├── ABIO Commands.md        # command index → commands/
├── Spec Language Reference.md  # comprehensive language spec
├── classes/                # individual class docs
│   ├── infra/              # infrastructure classes (Entity, Bio, IO, Interpreter, Expr)
│   ├── biology/            # biology classes (Molecule, Reaction, Chemistry, etc.)
│   └── execution/          # execution classes (Action, Measurement, Simulator, etc.)
├── modules/                # individual module docs
└── commands/               # individual command docs

The classes/ folder is organized into three subsystems: - infra/ — Core infrastructure (Entity, Bio, IO, Interpreter, Expr) - biology/ — Biological objects (Atom, Molecule, Reaction, Chemistry, Compartment, Flow, etc.) - execution/ — Runtime execution (Action, Measurement, Simulator, State, Timeline, etc.)

Key Documents: - Spec Language Reference — Complete language specification - ABIO Protocols — All classes alphabetically - ABIO Modules — All modules alphabetically - ABIO Commands — All commands (CLI and Python)

API Docs¶

Location: docs/api/

Purpose: Auto-generated reference from Python docstrings.

Characteristics: - Generated by MkDocs autodoc - Shows exact signatures, parameters, return types - Low-level — what's in the code - Updated automatically when code changes

Contents: - Function and class signatures - Parameter documentation - Type annotations - Module structure

How They Connect¶

User Guide → Architecture¶

User Guide provides orientation, then links out:

<!-- In Core Spec (User Guide) -->
For complete tag reference, see [Spec Language Reference](<architecture/Spec Language Reference.md>).

Architecture → API¶

Architecture explains concepts, then links to code:

<!-- In Spec Language Reference -->
See [API Reference](<api/spec_lang.md>) for function signatures.

Cross-References¶

If you want...	Start with...	Then go to...
Quick start	User Guide	—
Complete spec	User Guide	Architecture
Function signature	Architecture	API Docs
Implementation details	API Docs	Source code

Documentation Conventions¶

Rules and patterns for consistent documentation.

Breadcrumbs¶

Every document (except root indexes) starts with a breadcrumb trail above the H1 heading:

 [Architecture Docs](<architecture/Architecture Docs.md>) → [Commands](<architecture/ABIO Commands.md>)

# Bio.fetch()

Important: Start with a single space before the first [[. This prevents Obsidian from auto-expanding the link when the document opens.

Leading space prevents link expansion on page load
Shows the path from root to current document
Uses → arrows between levels
Links use Obsidian wiki-link syntax: [[target|display text]]
Blank line between breadcrumbs and H1

Pipeline Diagrams¶

When showing the processing pipeline, use an inline HTML span within the sentence (not a separate callout):

This is the entry point for the processing pipeline: <span style="white-space: nowrap">name → <b>.fetch()</b> → dict → <b>.hydrate()</b> → entity → <b>.build()</b> → expanded → <b>.eval()</b> → result</span>

white-space: nowrap prevents line breaks within the pipeline
<b> tags emphasize method names
Pipeline flows inline with the descriptive text

Command Titles¶

Command documents use method-call syntax in titles:

Style	Example
✓ Good	`# Bio.fetch()`
✗ Avoid	`# fetch` or `# Fetch`

This makes it clear these are methods on the Bio class.

Typed Synopsis¶

Synopsis sections show type annotations for clarity:

entity: Entity = Bio.fetch(name: str)
module: Scope = Bio.fetch(path: str, as_scope=True)

Links¶

Wiki-links (Obsidian syntax): - Same folder: [[Document Name]] - With display text: [Commands](<architecture/ABIO Commands.md>) - To subfolder: [Bio.fetch()](<commands/ABIO Fetch.md>) - To section: [Spec Language Reference#Hydration Phases](<architecture/Spec Language Reference.md#hydration-phases>)

See Also sections at end of documents:

## See Also

- [fetch](<architecture/commands/ABIO Fetch.md>) — Previous stage: load from source
- [Spec Language Reference](<architecture/Spec Language Reference.md>) — Complete language specification

Tables¶

Use consistent column alignment: - Text columns: left-aligned - Checkmark columns: center-aligned (:---:) - Keep column widths reasonable

| Method | CLI | Description |
|--------|:---:|-------------|
| Bio.run() | ✓ | Execute scenario |

Section Dividers¶

Use --- horizontal rules to separate major sections, but not before every H2.

Document Structure¶

Standard sections for command/class documents:

Breadcrumbs — navigation path
H1 Title — method syntax for commands
One-line description — brief summary immediately after H1
Synopsis — CLI and Python usage with types
Description — what it does, when to use it
Sections — detailed documentation
Examples — practical usage patterns
See Also — related documents

Code Examples¶

Show output in comments:

scenario = Bio.fetch("baseline")
print(type(scenario))  # → Scenario

Use # → to indicate output/result.

Emphasis¶

Bold for important terms on first use
code for method names, file paths, and values
Italics sparingly, mainly for "unchanged" or notes in tables

Project Docs (Not Released)¶

Location: External to docs/ (author's project management)

Purpose: Personal organization for the project author.

Contents: - Roadmap, TODO lists - PRD, feature planning - Working notes

These are not part of the released documentation — they're project management artifacts.

Chronological Ordering¶

Reverse chronological (newest first) for documents that accumulate entries over time: - Todo — New items added at top - Notes — New notes added at top - Features — New features added at top - Log — New entries added at top

Forward chronological (oldest first) for documents with planned progression: - Roadmap — Milestones in execution order

Date Headers¶

For reverse-chronological documents, use H2 headers with dates:

## 2026-01-10 — Documentation Audit

- Found 12 open questions
- Added 40+ documentation todos
- Reviewed all Python modules

## 2026-01-08 — Spec Language Complete

- All tags implemented
- Tests passing

The date format is YYYY-MM-DD followed by — and a brief title.