# Documentation Guide

This guide explains how to work with the AWS Logs MCP documentation, which is built using MkDocs and managed with Poetry.

## Setup

### Prerequisites

Before you begin, make sure you have the following installed:

- [Python 3.8+](https://www.python.org/downloads/)
- [Poetry](https://python-poetry.org/docs/#installation)

### Installing Dependencies

We use Poetry to manage Python dependencies for the documentation. To set up:

```bash
# Install Poetry (if not already installed)
curl -sSL https://install.python-poetry.org | python3 -

# Install dependencies
cd aws-logs-mcp
poetry install
```

## Working with Documentation

### Running the Documentation Server Locally

To preview the documentation locally:

```bash
# Activate the virtual environment
poetry shell

# Start the MkDocs server
mkdocs serve
```

Then open your browser to [http://localhost:8000](http://localhost:8000) to see the live preview of the documentation. The server automatically reloads when you make changes to the documentation files.

### Building the Documentation

To build the documentation site without deploying:

```bash
poetry run mkdocs build
```

This will create a `site` directory with the built documentation.

## Documentation Structure

Our documentation is organized in the following structure:

```
docs/
├── index.md                        # Home page
├── getting-started/                # Getting started guides
│   ├── installation.md             # Installation instructions
│   └── configuration.md            # Configuration guide
├── usage/                          # Usage guides
│   ├── available-tools.md          # Available MCP tools
│   └── testing.md                  # Testing guide
├── architecture/                   # Architecture documentation
│   ├── overview.md                 # Architecture overview
│   ├── components.md               # System components
│   └── data-flow.md                # Data flow diagrams
├── guides/                         # In-depth guides
│   ├── error-handling.md           # Error handling guide
│   ├── security-best-practices.md  # Security best practices
│   ├── local-deployment.md         # Local deployment guide
│   └── troubleshooting.md          # Troubleshooting guide
├── contributing/                   # Contributing guides
│   └── documentation.md            # This file
├── api-reference.md                # API reference
└── stylesheets/                    # Custom CSS
    └── extra.css                   # Extra styling
```

## Adding New Documentation

1. Create the Markdown file in the appropriate directory
2. Add a reference to it in `mkdocs.yml` under the `nav` section
3. Use the following Markdown features:
   - Code blocks with syntax highlighting
   - Admonitions (notes, warnings, etc.)
   - Tables
   - Links to other pages

## MkDocs Features

### Code Highlighting

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

### Admonitions

!!! note
    This is a note admonition.

!!! warning
    This is a warning admonition.

!!! tip
    This is a tip admonition.

### Tables

| Name | Description |
|------|-------------|
| Tool 1 | Description of Tool 1 |
| Tool 2 | Description of Tool 2 |

## Deployment

Documentation is automatically deployed to GitHub Pages when changes are pushed to the main branch. The GitHub Actions workflow handles the deployment process.

To manually deploy the documentation:

```bash
poetry run mkdocs gh-deploy
```

## Best Practices

1. Keep documentation up-to-date with code changes
2. Use consistent terminology throughout the documentation
3. Include examples and use cases
4. Add diagrams where appropriate to explain complex concepts
5. Use clear, concise language
6. Organize content logically with proper headings
7. Test links to ensure they work correctly