📝 Documentation Guide¶

This guide explains how to write documentation for CellMage, with a focus on code examples and formatting.

🧩 Markdown Structure¶

CellMage documentation uses MyST Markdown, which is an extension of standard Markdown with additional features for technical documentation.

Headers Structure¶

# Level 1 - Top-level page title
## Level 2 - Major sections
### Level 3 - Subsections
#### Level 4 - Additional headings as needed

📊 Code Blocks and Examples¶

When including code examples:

For IPython/Magic Command Examples¶

%%llm
What is the capital of France?

Notice that we’re using the ipython language specifier above, not python. This is critical for all code blocks containing:

Magic commands (%llm_config, %%llm, etc.)
Question marks in prompts
Dollar signs (e.g., in financial examples)
Exclamation marks for shell commands
Triple backtick code blocks within code blocks

For Regular Python Code¶

def calculate_metrics(data):
    """Calculate basic statistics on the data."""
    return {
        "mean": sum(data) / len(data),
        "max": max(data),
        "min": min(data)
    }

For Shell Commands¶

pip install cellmage

🎭 Including Personas and Snippets Examples¶

When documenting the creation of persona or snippet files:

Create a file `llm_personas/data_analyst.md`:

```markdown
---
name: Data Analyst
model: gpt-4o
temperature: 0.3
---
You are a data analyst expert who specializes in interpreting data, finding patterns,
and creating visualizations to communicate insights.
```

🔄 Cross-References and Links¶

To refer to other pages in the documentation:

See [Magic Commands](../magic_commands.md) for more details.

For external links:

Visit the [GitHub repository](https://github.com/madpin/cellmage).

🖼️ Including Images¶

To include images:

![CellMage Workflow](../_static/images/cellmage_workflow.png)

📋 Tables¶

Tables are created with pipe syntax:

| Parameter | Description | Default |
|-----------|-------------|---------|
| `model` | The LLM model to use | `gpt-4o-mini` |
| `temperature` | Creativity setting | 0.7 |

🧠 Tips for Clear Documentation¶

Start with a clear introduction - Explain what the page covers and who it’s for.
Use consistent terminology - Stick to the same terms throughout.
Progressive disclosure - Start with simple examples, then show more complex ones.
Show real-world use cases - Demonstrate practical applications.
Include error handling - Show what happens when things go wrong.
Use callouts for important notes - Highlight key information.

Callout Example¶

⚠️ Warning: Make sure you have set your API key before running this command.

🔄 Fixing Lexer Errors in Documentation¶

If you encounter syntax highlighting errors when building the documentation:

For code blocks with CellMage magic commands, use ipython instead of python:
```
```ipython
%%llm
What is the capital of France?
```
```

For nested code blocks (code inside code examples), add an extra level of backticks:

````ipython
%%llm
```ipython
def example():
    return "This is nested code"
```
````

If you still encounter errors, consider using plain text blocks that don’t attempt syntax highlighting:
```
```text
%llm_config --model gpt-4o
```
```

Common Symbols Causing Lexer Errors¶

The following characters/symbols often cause lexer errors in Python code blocks but work correctly with ipython language specifier:

Symbol	Example	Solution
Question marks (`?`)	`%%llm What is the capital of France?`	Use `ipython` language
Dollar signs (`$`)	`Price: $25.99`	Use `ipython` language
Exclamation marks (`!`)	`!pip install cellmage`	Use `ipython` language
Triple backticks (```)	Code blocks inside prompts	Add extra backtick level
Mathematical symbols (`²`, `π`)	`O(n²)` complexity	Use `ipython` or `text`

Adding Code Examples to Documentation¶

When adding example code blocks to tutorials:

For magic commands and prompts with questions:

```ipython
%%llm
Compare the advantages of SQL and NoSQL databases?
```

For shell commands in IPython:

```ipython
!mkdir -p llm_snippets
!pip install "cellmage[all]"
```

For data that contains special characters:

```ipython
%%llm
The price dropped from $50 to $42.50. What's the percentage decrease?
```

Including Documentation in TOC¶

Make sure your documentation files are included in a table of contents (toctree) in an appropriate parent file. For example, to include this guide in the developer documentation toctree, add it to docs/source/developer/index.md:

```{toctree}
:maxdepth: 2
documentation_guide