Samir Boulahtit
f141cc4e6a
Move 39 documentation files from top-level docs/ into each module's docs/ folder, accessible via symlinks from docs/modules/. Create data-model.md files for 10 modules with full schema documentation. Replace originals with redirect stubs. Remove empty guide stubs. Modules migrated: tenancy, billing, loyalty, marketplace, orders, messaging, cms, catalog, inventory, hosting, prospecting. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
83 lines
3.3 KiB
Markdown
83 lines
3.3 KiB
Markdown
# Module Documentation Standard
|
|
|
|
This page defines the convention for where documentation lives in the Orion platform.
|
|
|
|
## Principle: Single Source of Truth
|
|
|
|
Every module owns its documentation in `app/modules/{name}/docs/`. The top-level `docs/modules/` directory contains **symlinks** to these module docs folders — never duplicate files.
|
|
|
|
## Module `docs/` Folder (Source of Truth)
|
|
|
|
Content specific to one module's internals lives inside the module:
|
|
|
|
```
|
|
app/modules/{name}/docs/
|
|
├── index.md # Module overview (REQUIRED)
|
|
├── data-model.md # Entity relationships, schema, field descriptions
|
|
├── api.md # API endpoints with request/response examples
|
|
├── business-logic.md # Algorithms, scoring, state machines, workflows
|
|
└── {topic}.md # Additional topic files as needed
|
|
```
|
|
|
|
### Required: `index.md`
|
|
|
|
Every module must have an `index.md` with this structure:
|
|
|
|
| Section | Content |
|
|
|---------|---------|
|
|
| **Overview table** | Code, classification, dependencies, status |
|
|
| **Features** | Feature list from `definition.py` |
|
|
| **Permissions** | Permission table (if any) |
|
|
| **Data Model** | Brief entity overview or "No database models." |
|
|
| **API Endpoints** | Summary table or "No API endpoints." |
|
|
| **Configuration** | Config keys or "No module-specific configuration." |
|
|
|
|
### Optional Files
|
|
|
|
| File | When to Create |
|
|
|------|---------------|
|
|
| `data-model.md` | Module has database models with non-trivial relationships |
|
|
| `api.md` | Module has API routes that need detailed request/response docs |
|
|
| `business-logic.md` | Module has complex algorithms, scoring, or state machines |
|
|
| Additional topic files | As needed (e.g., `scoring.md`, `wallet-integration.md`) |
|
|
|
|
## Top-Level `docs/`
|
|
|
|
Cross-cutting, architectural, or multi-module concerns:
|
|
|
|
| Directory | Content |
|
|
|-----------|---------|
|
|
| `docs/architecture/` | Module system design, cross-module import rules, middleware, multi-tenancy |
|
|
| `docs/development/` | How to create modules, coding standards, migration guides |
|
|
| `docs/deployment/` | Server setup, Docker, CI/CD |
|
|
| `docs/features/` | Feature guides that span multiple modules (e.g., email system touches messaging + tenancy) |
|
|
| `docs/guides/` | End-user / store-admin facing guides |
|
|
|
|
## Rule of Thumb
|
|
|
|
> If it's about **how one module works internally**, it goes in the module's `docs/`.
|
|
> If it's about **how modules interact** or **cross-cutting concerns**, it goes in top-level `docs/`.
|
|
|
|
## How Symlinks Work
|
|
|
|
The `docs/modules/` directory is populated with symlinks:
|
|
|
|
```bash
|
|
# Each module gets a symlink
|
|
docs/modules/{name} → ../../app/modules/{name}/docs
|
|
|
|
# Example
|
|
docs/modules/loyalty → ../../app/modules/loyalty/docs
|
|
docs/modules/billing → ../../app/modules/billing/docs
|
|
```
|
|
|
|
MkDocs follows these symlinks via its default configuration. When editing module docs, always edit the source files in `app/modules/{name}/docs/` — the symlinks ensure MkDocs picks them up automatically.
|
|
|
|
## Adding Documentation to a Module
|
|
|
|
1. Create `app/modules/{name}/docs/index.md` (use existing modules as reference)
|
|
2. Add optional files (`data-model.md`, `api.md`, etc.) as needed
|
|
3. Create the symlink: `ln -s ../../app/modules/{name}/docs docs/modules/{name}`
|
|
4. Add the nav entry in `mkdocs.yml` under the appropriate classification group
|
|
5. Run `mkdocs build --strict` to verify
|