Cursor AI

Understanding and Customizing Cursor

Demo Documentation Management

In this lesson, we’ll explore effective documentation strategies for Python projects—covering inline docstrings, external references, AI-generated content, and enforcing standards with Cursor AI.

What Is Documentation?

Documentation helps developers understand and maintain code. It can live:

  • Inline: within the code as docstrings or comments
  • External: on websites, wikis, or portals
Documentation TypeLocationProsCons
InlineDocstrings & commentsAlways with the code, easy to updateCan clutter code if overdone
ExternalInternal/External sitesRich formatting, centralizedMay drift out of sync

Inline Documentation

A PEP 8-compliant docstring example in Python:

def read_csv(file_path):
    """
    Read data from a CSV file and print each row.

    Args:
        file_path (str): Path to the CSV file.

    Returns:
        None: Prints rows to stdout, no return value.

    Example:
        >>> read_csv("data.csv")
        ['col1', 'col2']
        ['val1', 'val2']
    """
    import csv

    with open(file_path, "r") as f:
        csvreader = csv.reader(f)
        for row in csvreader:
            print(row)

Note

Well-structured docstrings improve readability and enable automatic tool support (e.g., Sphinx, MkDocs).

External Documentation

For broader context or API details, link out to a centralized docs site:

# Production: replace with a secure random key
app.config["SECRET_KEY"] = "dev"
app.config["DATABASE"] = os.path.join(app.instance_path, "task_manager.sqlite")

You can reference external guides:

Generating Documentation with AI Agents

Leverage AI to scan code and generate or enhance PEP 8-style docstrings automatically.

Example: app.py

import csv
import sqlite3
import os
from flask import Flask, g

# Initialize Flask app
app = Flask(__name__)
app.config["SECRET_KEY"] = "dev"  # Change for production
app.config["DATABASE"] = os.path.join(app.instance_path, "task_manager.sqlite")

def read_csv(file_path):
    with open(file_path, "r") as f:
        csvreader = csv.reader(f)
        for row in csvreader:
            print(row)

# Ensure the instance folder exists
os.makedirs(app.instance_path, exist_ok=True)

AI-Enhanced Version (agent prompt: “Create PEP 8 documentation for this file”):

def read_csv(file_path):
    """
    Read data from a CSV file and print each row.

    Args:
        file_path (str): Path to the CSV file.

    Returns:
        None

    Example:
        >>> read_csv("data.csv")
        ['header1', 'header2']
        ['value1', 'value2']
    """
    with open(file_path, "r") as f:
        csvreader = csv.reader(f)
        for row in csvreader:
            print(row)

Using Cursor AI Rules to Enforce Documentation Standards

Define a documentation_standards.mdc to guide every AI invocation:

# documentation_standards.mdc
# - Use clear, concise language.
# - Document all parameters and return values.
# - Include usage examples for non-trivial functions.
# - Follow PEP 8 formatting: docstring quotes, indentation, line length.
# - Highlight edge cases and error handling in examples.
# Apply standards to read_csv
import csv

def read_csv(file_path):
    """
    Read data from a CSV file and print each row.

    Args:
        file_path (str): Path to the CSV file.

    Returns:
        None

    Example:
        >>> read_csv("data.csv")
        ['header1', 'header2']
        ['value1', 'value2']
    """
    with open(file_path, "r") as f:
        csvreader = csv.reader(f)
        for row in csvreader:
            ...

The image shows a code editor with a split view. The left side displays a file directory, and the right side shows code and documentation guidelines for a Python project.

When you run the agent against a test file (e.g., test_app.py), it will produce a PEP 8-compliant suite:

# Write the content to the rule file
with open(rule_file_path, "w") as file:
    file.write(rule_content)

import os
import tempfile
import pytest

def test_read_csv(tmp_path):
    """
    Test read_csv with a temporary CSV file.
    """
    data = tmp_path / "test.csv"
    data.write_text("a,b\n1,2\n")
    read_csv(str(data))
    # assertions here...

The image shows a code editor with a Python script open, displaying documentation standards and test functions. The left sidebar lists project files, and the right side shows detailed comments and guidelines for generating documentation.

Best Practices for AI-Friendly Documentation

  • Keep prompts concise and focused on one file or function.
  • Group related rules and examples together in your standards file.
  • Include representative code snippets in your rule set.
  • Iterate on the rule file to refine style and edge-case coverage.
  • Review and edit generated docs for correctness and clarity.

By combining inline docstrings, external references, AI-generated content, and a robust rule set, you’ll ensure your Python code remains well-documented, consistent, and up to date.

Watch Video

Watch video content

Previous
Demo Privacy