Documentation Guide¶

This guide covers contributing to Code Scalpel's documentation.

Documentation Structure¶

website/docs/
├── index.md                 # Home page
├── getting-started/         # Getting started guides
├── tools/                   # Tool reference
│   ├── category/            # Tools by category
│   ├── tier/                # Tools by tier
│   └── deep-dive/           # Individual tool docs
├── tutorials/               # Step-by-step tutorials
├── configuration/           # Configuration reference
├── guides/                  # In-depth guides
├── api/                     # API reference
├── faq/                     # FAQ pages
├── releases/                # Release notes
└── contributing/            # Contributor guides

Building Docs Locally¶

# Install MkDocs and dependencies
pip install mkdocs-material mkdocs-jupyter mkdocs-minify-plugin \
            mkdocs-git-revision-date-localized-plugin mkdocs-glightbox

# Serve locally
cd website
mkdocs serve

# Build static site
mkdocs build

Visit http://localhost:8000 to preview.

Writing Documentation¶

Page Structure¶

Every page should have:

---
title: Page Title
description: Brief description for SEO and previews.
---

# Page Title

Introduction paragraph explaining what this page covers.

## Main Section

Content...

## Another Section

More content...

Front Matter¶

Required front matter:

---
title: Tool Name            # Page title
description: Brief desc...  # SEO description
---

Admonitions¶

Use admonitions for callouts:

!!! note
    Important information

!!! warning
    Potential issues

!!! tip
    Helpful suggestions

!!! danger
    Critical warnings

!!! example
    Code examples

Renders as:

Note

Important information

Warning

Potential issues

Code Blocks¶

With syntax highlighting:

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

With line numbers:

    ```python linenums="1"
    def hello():
        print("Hello, World!")
    ```

With highlighted lines:

    ```python hl_lines="2"
    def hello():
        print("Hello, World!")  # Highlighted
    ```

Tabs¶

For multiple alternatives:

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

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

Renders as tabs the reader can switch between.

Mermaid Diagrams¶

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

Tables¶

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

Links¶

Internal links:

[Link text](../path/to/page.md)
[Link with anchor](page.md#section-heading)

External links:

[External site](https://example.com)

Tool Documentation Template¶

For new tool pages in tools/deep-dive/:

---
title: tool_name
description: Brief description of the tool.
---

# tool_name

One-sentence description of what the tool does.

## Quick Reference

    ```python
    tool_name(
        param1: str,              # Description
        param2: int = 10,         # Description with default
    ) -> ResultType
    ```

## Parameters

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

## Response Schema

    ```json
    {
      "data": {
        "field1": "string",
        "field2": "integer"
      }
    }
    ```

## Examples

### Example Name

=== "AI Prompt"
        ```
        Natural language request
        ```

=== "Tool Call"
        ```json
        {"param1": "value"}
        ```

=== "Response"
        ```json
        {"data": {...}}
        ```

## Tier Differences

| Feature | Community | Pro | Enterprise |
|---------|-----------|-----|------------|
| Feature 1 | ✅ | ✅ | ✅ |
| Feature 2 | ❌ | ✅ | ✅ |

## Best Practices

1. First practice
2. Second practice

## Related Tools

- [related_tool](related-tool.md) - Brief description

Style Guidelines¶

Tone¶

Clear and concise - Get to the point
Professional - Avoid emojis in body text
Active voice - "Run the command" not "The command should be run"

Terminology¶

Use	Instead of
Run	Execute
Tool	Function/Method
AI agent	Bot/Assistant
Tier	Plan/Level

Formatting¶

Use bold for UI elements: Click Save
Use code for commands, parameters, values
Use italics sparingly for emphasis

Adding Pages¶

Create the markdown file in the appropriate directory
Add to navigation in mkdocs.yml:

nav:
  - Section:
    - New Page: path/to/new-page.md

Build and verify locally
Submit PR

Screenshots¶

Place in website/docs/assets/images/:

![Alt text](assets/images/screenshot.png)

Optimize images: - PNG for screenshots with text - WebP for photos (if supported) - Max width: 1200px

Jupyter Notebooks¶

For tutorials with runnable code:

# In tutorials/notebooks/
[Getting Started](tutorials/notebooks/getting-started.ipynb)

Configuration in mkdocs.yml:

plugins:
  - mkdocs-jupyter:
      include_source: true
      execute: false

Checking Your Work¶

Before submitting:

# Build and check for errors
mkdocs build --strict

# Serve and manually check
mkdocs serve

Check for: - Broken links - Missing images - Formatting issues - Spelling/grammar