Documentation Workflow

This repository uses in-repo, versioned documentation instead of a separate GitHub Wiki.

Why this approach

• docs stay aligned with the code
• documentation changes can be reviewed in pull requests
• examples and notebooks can evolve alongside implementation
• contributors do not need a separate editing surface

Structure

The documentation system is organized as:

• docs/index.md: docs home
• docs/tutorials/: runnable onboarding and practical workflows
• docs/architecture/: internal structure and design pages
• docs/reference/: API and repository reference
• root-level guide pages in docs/: subsystem-focused guides
• web/index.html: static landing page source for the site root
• docs/.vitepress/config.js: navigation and site structure for the /docs/ site

When to update docs

Update documentation whenever you:

• add or remove public exports
• change constructor contracts or tensor-shape expectations
• modify a training workflow
• introduce a new major subsystem
• add a new example notebook worth surfacing

Minimum documentation rule

For any meaningful user-facing change, update:

1. README.md if the landing page should change
2. one relevant page under docs/
3. one runnable example or notebook when the change affects workflows

Authoring guidance

• prefer accurate, minimal runnable examples
• document the public API before internal details
• avoid promising workflows that have not been validated in the repository
• link across pages so documentation behaves like a wiki, not isolated files
• prefer fenced code blocks with an explicit language like python or bash
• keep configuration docs aligned with foreblocks/config.py

Local preview

This repository now uses VitePress for the versioned documentation site. Install the Node dependencies first:

npm install

Then serve the docs locally:

npm run docs:dev

Or build a static site:

npm run docs:build

Related pages

• Home
• Overview
• Repository Map