Documentation Guide¶

How to maintain and contribute to TradAI documentation.

Quick Reference¶

Architecture¶

The documentation uses MkDocs Material and follows a symlink-based approach to avoid content duplication.

docs/                          # MkDocs source
├── index.md                   # Homepage (standalone)
├── quickstarts/               # Standalone quickstart guides
├── developer-guides/          # Standalone dev guides
├── runbooks/                  # Standalone runbooks
├── troubleshooting/           # Standalone troubleshooting
├── architecture/              # Symlinks → reports/final-architecture/
├── libs/                      # Symlinks → libs/*/README.md
├── services/                  # Symlinks → services/*/README.md
└── design/                    # Symlinks → libs/*/DESIGN.md

mkdocs.yml                     # Site configuration
scripts/prepare-docs.sh        # Creates symlinks before build

Symlinked Content¶

These sections pull content from source files (single source of truth):

To update these: Edit the source file, not the docs folder.

Standalone Content¶

These live directly in docs/ and are edited there:

• Quickstarts (docs/quickstarts/)
• Developer Guides (docs/developer-guides/)
• Runbooks (docs/runbooks/)
• Troubleshooting (docs/troubleshooting/)
• Glossary (docs/glossary.md)
• API Reference (docs/reference/api.md)

Adding New Content¶

Add a New Page¶

1. Create the markdown file in the appropriate directory:

   # Standalone page
   touch docs/developer-guides/my-new-guide.md
   

2. Add to mkdocs.yml navigation:

   nav:
     - Developer Guides:
         - developer-guides/index.md
         - My New Guide: developer-guides/my-new-guide.md  # Add here
   

3. Preview locally:

   just docs
   

Add a New Library/Service¶

1. Create the README.md in the source location:

   # For a new library
   touch libs/my-new-lib/README.md
   

2. Update scripts/prepare-docs.sh to include it:

   # Add to the library loop
   for lib in tradai-common tradai-data tradai-strategy my-new-lib; do
   

3. Add to mkdocs.yml navigation:

   - Libraries:
       - libs/index.md
       - my-new-lib: libs/my-new-lib.md
   

Add a New Section¶

1. Create directory and index:

   mkdir docs/my-section
   touch docs/my-section/index.md
   

2. Add to mkdocs.yml:

   nav:
     - My Section:
         - my-section/index.md
         - Page One: my-section/page-one.md
   

Writing Guidelines¶

Use Admonitions¶

Highlight important information with callouts:

!!! tip "Quick Tip"
    Use `just check` to run all validations.

!!! warning "Caution"
    This affects production data.

!!! danger "Breaking Change"
    Not backwards compatible.

!!! note "Note"
    Additional context here.

!!! info "Info"
    Background information.

Code Blocks¶

Always specify the language:

```bash
just setup

from tradai.common import BaseService

theme:
  name: material

### Tables

Use markdown tables for structured data:

```markdown
| Option | Description | Default |
|--------|-------------|---------|
| `--dry-run` | Simulate only | `false` |

Internal Links¶

Use relative paths:

See [Your First Backtest](../quickstarts/01-your-first-backtest.md)

Local Development¶

Preview Changes¶

# Start local server with hot reload
just docs

# Opens at http://127.0.0.1:8000

Build Static Site¶

# Build to site/ directory
just docs-build

# Check for broken links, missing files

Test Before Commit¶

1. Run just docs and check:
2. [ ] New pages render correctly
3. [ ] Navigation shows new items
4. [ ] Links work (no 404s)
5. [ ] Code blocks have syntax highlighting
6. [ ] Admonitions display properly

CI/CD Pipeline¶

Automatic Deployment¶

Documentation deploys automatically when these files change on main:

• docs/**
• mkdocs.yml
• libs/**/README.md
• libs/**/DESIGN.md
• services/**/README.md
• reports/final-architecture/**
• scripts/prepare-docs.sh

Manual Deployment¶

# Deploy from local machine
just docs-deploy

Workflow File¶

See .github/workflows/docs.yml for the full pipeline:

1. Checkout code
2. Install Python 3.11
3. Install system deps (cairo for social cards)
4. Install MkDocs and plugins
5. Run prepare-docs.sh (create symlinks)
6. Convert symlinks to files (for gh-pages)
7. Deploy with mkdocs gh-deploy

Configuration Reference¶

mkdocs.yml Structure¶

site_name: TradAI Documentation
site_url: https://tradai-bot.github.io/tradai-uv/
repo_url: https://github.com/tradai-bot/tradai-uv
edit_uri: edit/main/docs/          # Enables "Edit on GitHub"

theme:
  name: material
  favicon: assets/favicon.svg
  icon:
    logo: material/chart-line
    repo: fontawesome/brands/github
  palette:                          # Dark/light mode
    - scheme: slate
      toggle:
        icon: material/brightness-4
    - scheme: default
      toggle:
        icon: material/brightness-7
  features:
    - navigation.tabs              # Top tabs
    - navigation.sections          # Sidebar sections
    - search.suggest               # Search suggestions
    - content.code.copy            # Copy button on code
    - content.action.edit          # Edit on GitHub button

plugins:
  - search
  - social:                        # Social cards (CI only)
      enabled: !ENV [CI, false]
  - minify:
      minify_html: true

nav:                               # Site navigation
  - Home: index.md
  - Section:
      - section/index.md
      - Page: section/page.md

Adding Features¶

Troubleshooting¶

Symlink Errors¶

If symlinks break:

# Recreate all symlinks
./scripts/prepare-docs.sh

Missing Page in Nav¶

Check that: 1. File exists in docs/ or is symlinked 2. Entry exists in mkdocs.yml nav: section 3. Path matches exactly (case-sensitive)

Social Cards Not Generating Locally¶

Social cards require cairo library. On macOS:

brew install cairo

If still failing, social cards are CI-only (enabled: !ENV [CI, false]).

404 on GitHub Pages¶

1. Check site_url in mkdocs.yml matches your repo
2. Ensure GitHub Pages is enabled (Settings → Pages → gh-pages branch)
3. Wait 1-2 minutes after deployment

See Also¶

• MkDocs Material Documentation
• GitHub Pages