284 lines
7.6 KiB
Markdown
284 lines
7.6 KiB
Markdown
# VAPORA Documentation
|
|
|
|
Complete user-facing documentation for VAPORA, an intelligent development orchestration platform.
|
|
|
|
## Quick Navigation
|
|
|
|
- **[Getting Started](getting-started.md)** — Start here
|
|
- **[Quickstart](quickstart.md)** — Quick setup guide
|
|
- **[Setup & Deployment](setup/)** — Installation, configuration, deployment
|
|
- **[Features](features/)** — Capabilities and overview
|
|
- **[Architecture](architecture/)** — Design, planning, and system overview
|
|
- **[Integrations](integrations/)** — Integration guides and APIs
|
|
- **[Branding](branding.md)** — Brand assets and guidelines
|
|
- **[Executive Summary](executive/)** — Executive-level summaries
|
|
|
|
## Documentation Structure
|
|
|
|
```
|
|
docs/
|
|
├── README.md (this file - directory index)
|
|
├── getting-started.md (entry point)
|
|
├── quickstart.md (quick setup)
|
|
├── branding.md (brand guidelines)
|
|
├── setup/ (installation & deployment)
|
|
│ ├── README.md
|
|
│ ├── setup-guide.md
|
|
│ ├── deployment.md
|
|
│ ├── tracking-setup.md
|
|
│ └── ...
|
|
├── features/ (product capabilities)
|
|
│ ├── README.md
|
|
│ └── overview.md
|
|
├── architecture/ (design & planning)
|
|
│ ├── README.md
|
|
│ ├── project-plan.md
|
|
│ ├── phase1-integration.md
|
|
│ ├── completion-report.md
|
|
│ └── ...
|
|
├── integrations/ (integration guides)
|
|
│ ├── README.md
|
|
│ ├── doc-lifecycle.md
|
|
│ └── ...
|
|
└── executive/ (executive summaries)
|
|
├── README.md
|
|
├── executive-summary.md
|
|
└── resumen-ejecutivo.md
|
|
```
|
|
|
|
## mdBook Integration
|
|
|
|
### Overview
|
|
|
|
This documentation project is fully integrated with **mdBook**, a command-line tool for building books from markdown. All markdown files in this directory are automatically indexed and linked through the mdBook system.
|
|
|
|
### Directory Structure for mdBook
|
|
|
|
```
|
|
docs/
|
|
├── book.toml (mdBook configuration)
|
|
├── src/
|
|
│ ├── SUMMARY.md (table of contents - auto-generated)
|
|
│ ├── intro.md (landing page)
|
|
├── theme/ (custom styling)
|
|
│ ├── index.hbs (HTML template)
|
|
│ └── vapora-custom.css (custom CSS theme)
|
|
├── book/ (generated output - .gitignored)
|
|
│ └── index.html
|
|
├── .gitignore (excludes build artifacts)
|
|
│
|
|
├── README.md (this file)
|
|
├── getting-started.md (entry points)
|
|
├── quickstart.md
|
|
├── examples-guide.md (examples documentation)
|
|
├── tutorials/ (learning tutorials)
|
|
│
|
|
├── setup/ (installation & deployment)
|
|
├── features/ (product capabilities)
|
|
├── architecture/ (system design)
|
|
├── adrs/ (architecture decision records)
|
|
├── integrations/ (integration guides)
|
|
├── operations/ (runbooks & procedures)
|
|
└── disaster-recovery/ (recovery procedures)
|
|
```
|
|
|
|
### Building the Documentation
|
|
|
|
**Install mdBook (if not already installed):**
|
|
|
|
```bash
|
|
cargo install mdbook
|
|
```
|
|
|
|
**Build the static site:**
|
|
|
|
```bash
|
|
cd docs
|
|
mdbook build
|
|
```
|
|
|
|
Output will be in `docs/book/` directory.
|
|
|
|
**Serve locally for development:**
|
|
|
|
```bash
|
|
cd docs
|
|
mdbook serve
|
|
```
|
|
|
|
Then open `http://localhost:3000` in your browser. Changes to markdown files will automatically rebuild.
|
|
|
|
### Documentation Guidelines
|
|
|
|
#### File Naming
|
|
- **Root markdown**: UPPERCASE (README.md, CHANGELOG.md)
|
|
- **Content markdown**: lowercase (getting-started.md, setup-guide.md)
|
|
- **Multi-word files**: kebab-case (setup-guide.md, disaster-recovery.md)
|
|
|
|
#### Structure Requirements
|
|
- Each subdirectory **must** have a README.md
|
|
- Use relative paths for internal links: `[link](../other-file.md)`
|
|
- Add proper heading hierarchy: Start with h2 (##) in content files
|
|
|
|
#### Markdown Compliance (markdownlint)
|
|
1. **Code Blocks (MD031, MD040)**
|
|
- Add blank line before and after fenced code blocks
|
|
- Always specify language: \`\`\`bash, \`\`\`rust, \`\`\`toml
|
|
- Use \`\`\`text for output/logs
|
|
|
|
2. **Lists (MD032)**
|
|
- Add blank line before and after lists
|
|
|
|
3. **Headings (MD022, MD001, MD026, MD024)**
|
|
- Add blank line before and after headings
|
|
- Heading levels increment by one
|
|
- No trailing punctuation
|
|
- No duplicate heading names
|
|
|
|
### mdBook Configuration (book.toml)
|
|
|
|
Key settings:
|
|
|
|
```toml
|
|
[book]
|
|
title = "VAPORA Platform Documentation"
|
|
src = "src" # Where mdBook reads SUMMARY.md
|
|
build-dir = "book" # Where output is generated
|
|
|
|
[output.html]
|
|
theme = "theme" # Path to custom theme
|
|
default-theme = "light"
|
|
edit-url-template = "https://github.com/.../edit/main/docs/{path}"
|
|
```
|
|
|
|
### Custom Theme
|
|
|
|
**Location**: `docs/theme/`
|
|
|
|
- `index.hbs` — HTML template
|
|
- `vapora-custom.css` — Custom styling with VAPORA branding
|
|
|
|
Features:
|
|
- Professional blue/violet color scheme
|
|
- Responsive design (mobile-friendly)
|
|
- Dark mode support
|
|
- Custom syntax highlighting
|
|
- Print-friendly styles
|
|
|
|
### Content Organization
|
|
|
|
The `src/SUMMARY.md` file automatically indexes all documentation:
|
|
|
|
```
|
|
# VAPORA Documentation
|
|
|
|
## [Introduction](../README.md)
|
|
|
|
## Getting Started
|
|
- [Quick Start](../getting-started.md)
|
|
- [Quickstart Guide](../quickstart.md)
|
|
|
|
## Setup & Deployment
|
|
- [Setup Overview](../setup/README.md)
|
|
- [Setup Guide](../setup/setup-guide.md)
|
|
...
|
|
```
|
|
|
|
**No manual updates needed** — SUMMARY.md structure remains constant as new docs are added to existing sections.
|
|
|
|
### Deployment
|
|
|
|
**GitHub Pages:**
|
|
|
|
```bash
|
|
# Build the book
|
|
mdbook build
|
|
|
|
# Commit and push
|
|
git add docs/book/
|
|
git commit -m "chore: update documentation"
|
|
git push origin main
|
|
```
|
|
|
|
Configure GitHub repository settings:
|
|
- Source: `main` branch
|
|
- Path: `docs/book/`
|
|
- Custom domain: docs.vapora.io (optional)
|
|
|
|
**Docker (for CI/CD):**
|
|
|
|
```dockerfile
|
|
FROM rust:latest
|
|
RUN cargo install mdbook
|
|
|
|
WORKDIR /docs
|
|
COPY . .
|
|
RUN mdbook build
|
|
|
|
# Output in /docs/book/
|
|
```
|
|
|
|
### Troubleshooting
|
|
|
|
| Issue | Solution |
|
|
|-------|----------|
|
|
| Links broken in mdBook | Use relative paths: `../file.md` not `file.md` |
|
|
| Theme not applying | Ensure `theme/` directory exists, run `mdbook build --no-create-missing` |
|
|
| Search not working | Rebuild with `mdbook build` |
|
|
| Build fails | Check for invalid TOML in `book.toml` |
|
|
|
|
### Quality Assurance
|
|
|
|
**Before committing documentation:**
|
|
|
|
```bash
|
|
# Lint markdown
|
|
markdownlint docs/**/*.md
|
|
|
|
# Build locally
|
|
cd docs && mdbook build
|
|
|
|
# Verify structure
|
|
cd docs && mdbook serve
|
|
# Open http://localhost:3000 and verify navigation
|
|
```
|
|
|
|
### CI/CD Integration
|
|
|
|
Add to `.github/workflows/docs.yml`:
|
|
|
|
```yaml
|
|
name: Documentation
|
|
|
|
on:
|
|
push:
|
|
paths:
|
|
- 'docs/**'
|
|
branches: [main]
|
|
|
|
jobs:
|
|
build:
|
|
runs-on: ubuntu-latest
|
|
steps:
|
|
- uses: actions/checkout@v3
|
|
- uses: peaceiris/actions-mdbook@v4
|
|
- run: cd docs && mdbook build
|
|
- uses: peaceiris/actions-gh-pages@v3
|
|
with:
|
|
github_token: ${{ secrets.GITHUB_TOKEN }}
|
|
publish_dir: ./docs/book
|
|
```
|
|
|
|
---
|
|
|
|
## Content Standards
|
|
|
|
Ensure all documents follow:
|
|
- Lowercase filenames (except README.md)
|
|
- Kebab-case for multi-word files
|
|
- Each subdirectory has README.md
|
|
- Proper heading hierarchy
|
|
- Clear, concise language
|
|
- Code examples when applicable
|
|
- Cross-references to related docs
|