# Update Docs

> Review changes on the current branch and update documentation to reflect new or changed functionality Use when this capability is needed.

- Skill: `tomevault-io/update-docs-22` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/update-docs-22`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/update-docs-22/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/update-docs-22

---


# Update Documentation

Review changes on the current branch (vs `main`) and update the MkDocs documentation site to reflect new or changed functionality.

## Documentation Architecture

The docs use **MkDocs Material** with **mkdocstrings** for auto-generated API reference. Config is in `mkdocs.yml`.

### What auto-updates (no action needed)

API reference pages in `docs/reference/` use `:::` mkdocstrings directives that render docs directly from source docstrings. When you add/change docstrings in source code, the API reference updates automatically on next build. **No manual edits needed for API reference pages unless a new module is added.**

### What requires manual updates

| Doc Area | Location | When to Update |
|----------|----------|----------------|
| **Guides** | `docs/guides/*.md` | New features, changed APIs, new patterns |
| **API reference pages** | `docs/reference/**/*.md` | New modules/packages added |
| **Examples gallery** | `docs/examples/*.md` | New example files added |
| **mkdocs.yml nav** | `mkdocs.yml` | New pages added |
| **Landing page** | `docs/index.md` | Major new capabilities |
| **Installation** | `docs/installation.md` | New dependencies or extras |

## Instructions

### 1. Identify what changed

```bash
# Files changed on this branch vs main
git diff --name-only main...HEAD

# Detailed diff for source code changes
git diff main...HEAD -- happysimulator/

# New example files
git diff --name-only --diff-filter=A main...HEAD -- examples/

# Changes to public API
git diff main...HEAD -- happysimulator/__init__.py
```

### 2. Determine which docs need updates

Check each category:

**New module/package added?**
→ Create a new `docs/reference/<area>/<name>.md` page with a `:::` directive
→ Add it to the `nav:` section in `mkdocs.yml`

**New component or feature?**
→ Update the relevant guide in `docs/guides/` (e.g., new queue policy → update `queuing-and-resources.md`)
→ If it's a major new capability, consider whether it needs its own guide page

**Changed API (renamed, new params, removed)?**
→ Update any guide that references the old API
→ Docstring changes auto-propagate to reference pages

**New example file added?**
→ Add a row to the relevant `docs/examples/<category>.md` gallery page
→ Update the count in `docs/examples/index.md`

**New dependencies or extras?**
→ Update `docs/installation.md`

### 3. Apply updates

For each doc file that needs changes:

1. **Read the existing file** to understand its structure
2. **Make minimal, targeted edits** that match the existing style
3. **Keep code examples correct** — no references to removed APIs (e.g., the old `callback=` parameter)
4. **Maintain cross-links** between guides and reference pages

### 4. Verify

```bash
python -m mkdocs build
```

Check for errors. Warnings about docstring formatting in source files are acceptable; warnings about missing pages or broken nav entries are not.

## Guide File Reference

| Guide | Covers |
|-------|--------|
| `guides/getting-started.md` | First simulation, Source→Server→Sink, M/M/1 |
| `guides/core-concepts.md` | Instant, Duration, Event, Entity, Simulation, clock injection |
| `guides/generators-and-futures.md` | yield forms, SimFuture, any_of, all_of |
| `guides/load-generation.md` | Source factories, profiles, custom providers |
| `guides/queuing-and-resources.md` | Queue, QueuedResource, Resource, rate limiters, Inductor |
| `guides/observability.md` | Data, Probe, collectors, SimulationSummary, analysis |
| `guides/simulation-control.md` | pause/resume, stepping, breakpoints, hooks |
| `guides/visual-debugger.md` | serve(), Chart, transforms, UI features |
| `guides/networking.md` | Network, links, conditions, partitions |
| `guides/clocks.md` | NodeClock, FixedSkew, LinearDrift, logical clocks |
| `guides/distributed-systems.md` | Raft, Paxos, CRDTs, replication, locks |
| `guides/behavioral-modeling.md` | Agent, Population, Environment, decisions, influence |
| `guides/industrial-simulation.md` | Industrial component catalog, composition |
| `guides/fault-injection.md` | FaultSchedule, breakdowns, partitions |
| `guides/logging.md` | Console/file/JSON logging, env vars |
| `guides/testing-patterns.md` | Deterministic testing, fixtures, seeds |

## API Reference Page Template

When adding a new reference page for a new module:

```markdown
# Module Name

Brief one-sentence description of what this module provides.

::: happysimulator.path.to.module
```

## Example Gallery Entry Template

When adding a new example to a gallery page:

```markdown
| [example_name.py](https://github.com/adamfilli/happy-simulator/blob/main/examples/category/example_name.py) | One-line description |
```

## Output

Provide a summary of what was updated:

```
## Changes Analyzed
- <list of relevant changes on this branch>

## Documentation Updates
- <what was added/changed in docs and why>

## No Updates Needed
- <areas checked that don't need changes>
```

If no documentation updates are needed, explain why (e.g., "internal refactoring with no API changes").

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/adamfilli) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-11 -->