Blog Details

Scenario:

You’ve written several Python functions and scripts for your project, but there’s no documentation. You want your code to be understandable for others (or future you). Your AI assistant can generate clear, structured documentation automatically.

Step 0: Define Your Goal

Example: You have this function:

def factorial(n):
    if n < 0:
        raise ValueError("Input must be non-negative")
    result = 1
    for i in range(2, n+1):
        result *= i
    return result

Goal: Create a docstring, a function summary, and optionally a Markdown or HTML documentation page for the project.

Step 1: Craft the AI Prompt

Treat AI as a technical writer or documentation assistant. Include:

1. The code snippet
2. Desired output format: docstring, Markdown, or full HTML
3. Optional: explain logic in simple terms

Example Prompt:

Generate documentation for this Python function. Include a docstring, a description of inputs and outputs, and a short example usage.

Step 2: AI Output Example (Docstring)

def factorial(n: int) -> int:
    """
    Calculate the factorial of a non-negative integer n.

    Parameters:
        n (int): A non-negative integer.

    Returns:
        int: The factorial of the input n.

    Raises:
        ValueError: If n is negative.

    Example:
        >>> factorial(5)
        120
    """
    if n < 0:
        raise ValueError("Input must be non-negative")
    result = 1
    for i in range(2, n+1):
        result *= i
    return result

Step 3: Generate Full Project Documentation

You can also ask AI to create a Markdown or HTML page for multiple functions:

Prompt Example:

I have these Python functions: factorial(), is_prime(), and reverse_string(). 
Generate a Markdown file documenting all functions, with descriptions, inputs, outputs, and examples.

AI Output Example (Markdown Snippet):

# Project Documentation

## factorial(n)
Calculate the factorial of a non-negative integer n.

**Parameters:** n (int)  
**Returns:** int  
**Raises:** ValueError if n is negative  
**Example:** `factorial(5) -> 120`

## is_prime(n)
Check if a number n is prime.

**Parameters:** n (int)  
**Returns:** bool  
**Example:** `is_prime(7) -> True`

## reverse_string(s)
Reverse a string s.

**Parameters:** s (str)  
**Returns:** str  
**Example:** `reverse_string("hello") -> "olleh"`

Step 4: Mini Lab Challenges

1. Generate docstrings for all functions in your current project.
2. Ask AI to create Markdown documentation for a small script with 3–5 functions.
3. Generate HTML documentation with sections and code blocks for web-friendly reference.
4. Challenge: Ask AI to simplify explanations so beginners can understand your code easily.

Step 5: Pro Tips

• Treat AI as a technical writer or coding teacher for clarity.
• Use consistent docstring style (Google, NumPy, or reStructuredText).
• Generate Markdown or HTML to share with team members or post online.
• Iteratively refine prompts for clarity, completeness, and style.
• Encourage AI to add examples and edge cases in documentation.

Lab Summary

• Documentation is essential for readability, collaboration, and learning.
• AI can automatically generate docstrings, Markdown, and HTML docs.
• Clear prompts + examples = high-quality documentation.
• Iteratively review AI output and refine for style, clarity, and accuracy.