tomevault-io 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
# 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:
- Read the existing file to understand its structure
- Make minimal, targeted edits that match the existing style
- Keep code examples correct — no references to removed APIs (e.g., the old
callback=parameter) - Maintain cross-links between guides and reference pages
4. Verify
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:
# 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:
| [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 — claim your Tome and manage your conversions.