Documentation Guide

Complete guide for adding documentation to SkyPortal.ai Docs

This guide shows you the simple pattern for adding new documentation pages. Everything is designed to be straightforward and consistent.

🎯 Philosophy

• Keep it simple: Use plain Markdown
• Follow patterns: Copy templates and adapt
• Be consistent: Use the same structure across pages
• Show examples: Include code and visuals
• Make it easy: Anyone on the team should be able to add docs

📁 Project Structure

docs.skyportal.ai/
├── docs/                      # All documentation content
│   ├── index.md              # Homepage
│   ├── getting-started/      # Getting started guides
│   ├── user-guide/           # User documentation
│   ├── api-reference/        # API documentation
│   ├── development/          # Developer docs
│   └── DOC_GUIDE.md         # This file
├── mkdocs.yml                # Configuration
├── requirements.txt          # Dependencies
└── README.md                 # Project info

✨ Quick Start

1. Create New Page

# Choose the right folder for your content
cd docs/user-guide/

# Create your page
touch my-new-feature.md

2. Add Content Using Templates

See Page Templates below for different page types.

3. Add to Navigation

Edit mkdocs.yml:

nav:
  - Home: index.md
  - Getting Started: getting-started/index.md
  - User Guide:
      - user-guide/index.md
      - My New Feature: user-guide/my-new-feature.md  # Add here
  - API Reference: api-reference/index.md
  - Development: development/index.md

4. Preview

mkdocs serve

Open http://localhost:8000 and see your page!

📝 Page Templates

Tutorial Page Template

Use for step-by-step guides:

# Page Title

Brief introduction explaining what this page covers.

## Prerequisites

What users need before starting:

- Requirement 1
- Requirement 2
- Requirement 3

## Step 1: First Step

Explanation of the first step.

\```bash
# Commands or code examples
command here
\```

## Step 2: Next Step

Continue with clear instructions.

## Verification

How to verify it worked:

\```python
# Verification code
result = verify()
assert result == expected
\```

## Troubleshooting

Common issues and solutions.

## Next Steps

- [Related Topic 1](link.md)
- [Related Topic 2](link.md)

Reference Page Template

Use for comprehensive reference material:

# Feature Reference

Complete reference for Feature X.

## Overview

Brief description of what this feature does and when to use it.

## Syntax

\```python
function_name(param1, param2, option=value)
\```

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| param1 | string | Yes | Description |
| param2 | int | No | Description |

## Examples

### Basic Usage

\```python
# Simple example
result = function_name("value", 42)
\```

### Advanced Usage

\```python
# More complex example
result = function_name(
    "value",
    42,
    option="custom"
)
\```

## Common Patterns

Frequently used patterns and best practices.

Concept Page Template

Use for explaining concepts:

# Concept Name

Explain what this concept is about.

## What is X?

Clear definition and explanation.

## Why Use X?

Benefits and use cases.

## How X Works

Explanation with diagrams if helpful:

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

## Key Components

### Component 1

Description

### Component 2

Description

## Best Practices

Tips and recommendations.

## Related Topics

- [Related Concept](link.md)
- [Implementation Guide](link.md)

API Documentation Template

Use for API endpoints:

# API: Resource Name

Documentation for the Resource API.

## Endpoints

### List Resources

Get all resources.

**Endpoint:** `GET /api/resources`

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| limit | integer | Maximum results |
| offset | integer | Pagination offset |

**Example:**

\```python
import requests

response = requests.get(
    "https://api.skyportal.ai/resources",
    params={"limit": 10},
    headers={"Authorization": f"token {token}"}
)

data = response.json()
\```

**Response:**

\```json
{
  "status": "success",
  "data": [
    {
      "id": 1,
      "name": "Resource 1"
    }
  ]
}
\```

### Create Resource

Create a new resource.

**Endpoint:** `POST /api/resources`

**Body:**

\```json
{
  "name": "New Resource",
  "value": 42
}
\```

**Example:**

\```python
response = requests.post(
    "https://api.skyportal.ai/resources",
    json={"name": "New Resource", "value": 42},
    headers={"Authorization": f"token {token}"}
)
\```

🎨 Markdown Features

Headers

# H1 - Page Title (use once per page)
## H2 - Main Sections
### H3 - Subsections
#### H4 - Details (use sparingly)

Code Blocks

Always specify the language:

```python
def hello():
    print("Hello")
```

```javascript
console.log("Hello");
```

```bash
mkdocs serve
```

Admonitions

For callouts and notices:

!!! note
    This is a note.

!!! tip "Pro Tip"
    This is a helpful tip!

!!! warning
    Important warning!

!!! info
    Additional information.

Code Tabs

For multi-language examples:

=== "Python"
    ```python
    print("Hello")
    ```

=== "JavaScript"
    ```javascript
    console.log("Hello");
    ```

=== "Bash"
    ```bash
    echo "Hello"
    ```

Tables

| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Value 1  | Value 2  | Value 3  |
| Value 4  | Value 5  | Value 6  |

Links

[Link text](relative/path/to/page.md)
[External link](https://skyportal.ai)

Images

![Alt text](../assets/image.png)

Lists

Unordered:
- Item 1
- Item 2
- Item 3

Ordered:
1. First step
2. Second step
3. Third step

Mermaid Diagrams

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

```mermaid
sequenceDiagram
    User->>API: Request
    API->>DB: Query
    DB->>API: Result
    API->>User: Response
\```

📐 Style Guide

Writing Style

• Clear and concise: Use simple language
• Active voice: "Click the button" not "The button should be clicked"
• Present tense: "The function returns" not "will return"
• Second person: "You can configure" not "One can configure"

Structure

1. Title: Clear, descriptive H1
2. Introduction: Brief overview (2-3 sentences)
3. Sections: Logical organization with H2/H3
4. Examples: Concrete code examples
5. Next steps: Links to related topics

Code Examples

• Test your code: All examples should work
• Include context: Show imports and setup
• Add comments: Explain complex parts
• Show output: Include expected results

🚀 Publishing Workflow

1. Local Preview

# Start development server
mkdocs serve

# View at http://localhost:8000
# Changes reload automatically

2. Build Test

# Build with strict mode (catches errors)
mkdocs build --strict

# Check for warnings
# Fix any issues before committing

3. Commit Changes

git add docs/
git commit -m "Add documentation for [feature]"
git push

4. Deploy

If auto-deploy is configured (GitHub Pages/Actions), changes deploy automatically when pushed to main branch.

🎯 Best Practices

Do's ✅

• Use templates: Start with a template above
• Show examples: Include working code
• Link related pages: Help users navigate
• Test locally: Always preview before committing
• Keep it updated: Update docs when features change
• Be consistent: Follow existing patterns

Don'ts ❌

• Don't overcomplicate: Keep it simple
• Don't skip examples: Always include code samples
• Don't ignore errors: Fix build warnings
• Don't duplicate: Link instead of repeating
• Don't use images for text: Use actual text
• Don't forget navigation: Add pages to mkdocs.yml

🏃 Common Tasks

Add a New Section

1. Create folder: docs/new-section/
2. Add index: docs/new-section/index.md
3. Update navigation in mkdocs.yml

nav:
  - New Section:
      - new-section/index.md
      - Page 1: new-section/page1.md
      - Page 2: new-section/page2.md

Add Images

1. Create docs/assets/ folder if needed
2. Add images to docs/assets/
3. Reference in markdown:

![Description](../assets/image.png)

Add External Links

[SkyPortal.ai](https://skyportal.ai)
[Internal Tool](https://internal.skyportal.ai)

🐛 Troubleshooting

Page Not Showing

• ✅ Check mkdocs.yml navigation
• ✅ Verify file path is correct
• ✅ Restart mkdocs serve

Links Broken

• ✅ Use relative paths
• ✅ Include .md extension
• ✅ Check file exists

Images Not Loading

• ✅ Verify image path
• ✅ Use relative paths (../assets/)
• ✅ Check image file exists

Build Errors

# See detailed errors
mkdocs build --verbose

# Common fixes:
# - Fix Markdown syntax
# - Complete unfinished sections
# - Fix broken links

📚 Resources

MkDocs

• MkDocs Documentation
• Material Theme
• Mermaid Diagrams

Markdown

• Markdown Guide
• Markdown Cheatsheet

Examples

Look at existing pages in this repo for examples of structure, styling, and formatting.

---

Ready to contribute? Pick a template, create your page, and start writing! 🚀