Skip to content

Documentation Quick Reference

Building Documentation

Local Development Server

# Serve docs with live reload
cd ai-tutor-backend
mkdocs serve

# Access at http://127.0.0.1:8000

Build Static Site

# Build static HTML
mkdocs build

# Output in site/ directory

Deploy to GitHub Pages (Optional)

# Deploy to gh-pages branch
mkdocs gh-deploy

Documentation Structure

Following the Diátaxis framework:

Tutorials (Learning-Oriented)

  • docs/tutorials/getting-started.md - First-time setup guide

How-To Guides (Task-Oriented)

  • docs/how-to/local-development.md - Daily development workflow
  • docs/how-to/database-migrations.md - Managing Alembic migrations
  • docs/how-to/testing.md - Running and writing tests

Reference (Information-Oriented)

  • docs/reference/api.md - Complete API endpoint reference
  • docs/reference/configuration.md - All environment variables
  • docs/reference/database-schema.md - Database model reference

Explanation (Understanding-Oriented)

  • docs/explanation/architecture.md - System design and patterns
  • docs/explanation/authentication.md - Auth/security deep dive

Adding New Documentation

1. Create Markdown File

# Example: Add new how-to guide
touch docs/how-to/deployment.md

2. Update mkdocs.yml

nav:
  - How-To Guides:
      - Deployment: how-to/deployment.md  # Add this line

3. Write Content

Use Markdown with Material for MkDocs extensions:

# Title

## Section

Content here.

!!! note "Note Box"
    Important information

!!! warning "Warning"
    Be careful with this

```python
# Code blocks with syntax highlighting
def example():
    pass
\```

Material for MkDocs Features

Admonitions

!!! note
    General note

!!! tip
    Helpful suggestion

!!! warning
    Caution required

!!! danger
    Critical warning

Tabs

=== "Tab 1"
    Content for tab 1

=== "Tab 2"
    Content for tab 2

Code Annotations

\```python
code here  # (1)
\```

1. Explanation appears as annotation

Tables

| Column 1 | Column 2 |
|----------|----------|
| Value 1  | Value 2  |

Mermaid Diagrams

```mermaid
graph LR
    A[Start] --> B[Process]
    B --> C[End]
\```

Configuration (mkdocs.yml)

Key sections:

site_name: Project Name
theme:
  name: material
  features:
    - navigation.tabs
    - search.suggest
plugins:
  - search
  - mkdocstrings  # For auto-generating API docs from docstrings
markdown_extensions:
  - admonition
  - pymdownx.highlight
  - pymdownx.superfences

Updating Documentation

After Code Changes

  1. Update relevant docs if API or behavior changes
  2. Add new docs for new features
  3. Update examples if needed
  4. Rebuild docs to verify

Review Checklist

  • Accurate information
  • Working code examples
  • Proper formatting
  • Links work
  • Builds without errors

Troubleshooting

Build Errors

# Check for syntax errors
mkdocs build --strict

# Verbose output
mkdocs build --verbose

MkDocs warns about broken internal links during build. Fix them before deploying.

Missing Pages

Ensure all pages listed in nav: section of mkdocs.yml exist.

Best Practices

  1. Keep docs close to code - Update docs with code changes
  2. Use clear examples - Show, don't just tell
  3. Test code samples - Ensure examples actually work
  4. Link between docs - Help readers navigate
  5. Update regularly - Docs should reflect current state
  6. Follow Diátaxis - Put content in the right category

Next Steps