Local Documentation Development¶

This guide explains how to work with the documentation locally.

Prerequisites¶

Install MkDocs and the Material theme:

pip install mkdocs mkdocs-material

Or using a virtual environment (recommended):

# Create virtual environment
python -m venv venv

# Activate it
source venv/bin/activate  # On macOS/Linux
# or
venv\Scripts\activate     # On Windows

# Install dependencies
pip install mkdocs mkdocs-material

Quick Start¶

Serve Documentation Locally¶

# Using npm script (recommended)
npm run docs:serve

# Or directly with mkdocs
mkdocs serve

This will start a local server at http://127.0.0.1:8000/

The server will automatically reload when you make changes to the documentation files.

Build Documentation¶

To build the static site (outputs to site/ directory):

# Using npm script
npm run docs:build

# Or directly with mkdocs
mkdocs build

Deploy to GitHub Pages¶

To deploy the documentation to GitHub Pages:

# Using npm script
npm run docs:deploy

# Or directly with mkdocs
mkdocs gh-deploy

Documentation Structure¶

docs/
├── index.md                          # Home page
├── getting-started.md                # Getting started guide
├── how-it-works.md                   # How the generator works
├── configuration.md                  # Configuration reference
├── mcp-configuration.md              # MCP server configuration
├── deployments.md                    # Deployment targets & inference
├── ci-integration.md                 # CI integration harness
├── EXAMPLES.md                       # Usage examples
├── TROUBLESHOOTING.md                # Troubleshooting guide
├── CONTRIBUTING.md                   # Contributing guide
├── how-it-works.md                   # Architecture overview
├── dev/
│   ├── schema-driven-architecture.md # Generator internals (schema → codegen)
│   ├── template-system.md            # EJS templates & do/ scripts
│   ├── mcp-server-development.md     # MCP server development
│   ├── registries-and-catalogs.md    # Catalog JSON format & data flow
│   └── testing.md                    # Testing guide
├── snippets/
│   ├── ai-frameworks-table.md        # Reusable table snippets
│   ├── architecture-diagram.md
│   ├── framework-table.md
│   ├── ml-frameworks-table.md
│   └── web-server-table.md
├── stylesheets/
│   └── extra.css                     # Custom styles
└── logo.png                          # Project logo

The canonical navigation structure is defined in mkdocs.yml. Pages not listed in the nav are excluded from the built site.

Making Changes¶

1. Edit Documentation Files¶

Documentation files are in the docs/ directory and use Markdown format.

2. Preview Changes¶

Start the local server to see your changes in real-time:

npm run docs:serve

3. Check for Broken Links¶

MkDocs will warn you about broken internal links when building. Use --strict to treat warnings as errors:

mkdocs build --strict

4. Test the Build¶

Before deploying, always test the build locally:

# Build the site
npm run docs:build

# Serve the built site
cd site
python -m http.server 8000

MkDocs Configuration¶

The documentation is configured in mkdocs.yml:

Theme: Material for MkDocs
Features: Navigation tabs, search, code highlighting
Extensions: Admonitions, code blocks, tables, etc.

Common Tasks¶

Add a New Page¶

Create a new .md file in docs/
Add it to the navigation in mkdocs.yml:

nav:
  - Home: index.md
  - Your New Page: your-new-page.md

Add Images¶

Place images in docs/ directory
Reference them in Markdown:

![Alt text](image.png)

Add Code Blocks¶

Use fenced code blocks with language specification:

```python
def hello():
    print("Hello, world!")
```

Add Admonitions¶

Use admonitions for notes, warnings, etc.:

!!! note
    This is a note.

!!! warning
    This is a warning.

!!! tip
    This is a tip.

Add Mermaid Diagrams¶

Use fenced code blocks with the mermaid language:

```mermaid
graph TD
    A[Start] --> B[End]
```

Add Tabbed Content¶

Use tabbed blocks for alternative instructions:

=== "macOS/Linux"

    ```bash
    source venv/bin/activate
    ```

=== "Windows"

    ```bash
    venv\Scripts\activate
    ```

Include Snippets¶

Reusable content lives in docs/snippets/. Include them with:

| Framework | Model Formats | Use Case | Category |
|-----------|---------------|----------|----------|
| scikit-learn | pkl, joblib | Classification, regression, clustering | Predictive ML |
| XGBoost | json, model, ubj | Gradient boosting, tabular data | Predictive ML |
| TensorFlow | keras, h5, SavedModel | Deep learning, neural networks | Predictive ML |
| vLLM | N/A (HuggingFace Hub) | Large language models, chat, text generation | Generative AI |
| SGLang | N/A (HuggingFace Hub) | Large language models, chat, text generation | Generative AI |
| TensorRT-LLM | N/A (HuggingFace Hub) | Large language models, chat, text generation | Generative AI |
| LMI | N/A (HuggingFace Hub) | Large language models, chat, text generation | Generative AI |
| DJL | N/A (HuggingFace Hub) | Large language models, chat, text generation | Generative AI |
| llama.cpp | GGUF (HuggingFace Hub) | Large language models on CPU or GPU | Generative AI |
| vLLM-Omni | N/A (HuggingFace Hub) | Image generation, multimodal | Generative AI |

Troubleshooting¶

MkDocs Not Found¶

If you get "command not found: mkdocs":

# Make sure it's installed
pip install mkdocs mkdocs-material

# Or check if it's in your PATH
which mkdocs

Port Already in Use¶

If port 8000 is already in use:

# Use a different port
mkdocs serve -a localhost:8001

Changes Not Showing¶

If changes aren't showing up:

Hard refresh your browser (Cmd+Shift+R on Mac, Ctrl+Shift+R on Windows)
Clear browser cache
Restart the MkDocs server

Build Errors¶

If you get build errors:

Check for syntax errors in Markdown files
Verify all referenced files exist
Check mkdocs.yml for configuration errors

Resources¶

GitHub Pages Deployment¶

The documentation is automatically deployed to GitHub Pages when you run:

npm run docs:deploy

This will: 1. Build the documentation 2. Push it to the gh-pages branch 3. GitHub will automatically serve it at: https://awslabs.github.io/ml-container-creator/

Manual Deployment¶

If automatic deployment doesn't work:

# Build the site
mkdocs build

# The built site is in the site/ directory
# You can manually push this to the gh-pages branch

Tips¶

Use Live Reload: Keep mkdocs serve running while editing
Check Links: Always build before deploying to catch broken links
Test Locally: Test the built site before deploying
Use Admonitions: Make important information stand out
Add Code Examples: Include practical examples in documentation
Keep It Updated: Update docs when adding features

NPM Scripts Reference¶

npm run docs:serve   # Start local documentation server
npm run docs:build   # Build static documentation site
npm run docs:deploy  # Deploy to GitHub Pages