AI for Documentation Generation — Complete Guide

from OpenAI import OpenAI
import os

client = OpenAI()

def generate_readme(repo_path):
    """Generate a README.md from a Repository's code and structure."""
    project_name = os.path.basename(repo_path)

    # Gather project information
    files = []
    for root, dirs, filenames in os.walk(repo_path):
        dirs[:] = [d for d in dirs if d not in [".Git", "__pycache__", "node_modules"]]
        for f in filenames:
            if f.endswith((".py", ".js", ".ts", ".Go", ".rs", ".md")):
                filepath = os.path.join(root, f)
                with open(filepath) as fh:
                    content = fh.read()
                files.append({"path": os.path.relpath(filepath, repo_path),
                             "content": content[:500]})

    # Build project summary for AI
    project_summary = f"Project: {project_name}\nFiles: {len(files)}\n"
    for f in files[:10]:
        project_summary += f"\n--- {f['path']} ---\n{f['content']}\n"

    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[{
            "role": "system",
            "content": ""]
You are a technical documentation expert. Generate a comprehensive README.md
based on the project files provided. Include:

1. Project title and one-sentence description
2. Features list (from code analysis)
3. Installation instructions
4. Quick start example (from actual code)
5. API or usage documentation
6. Configuration options
7. Contributing guidelines
8. License information (infer from project)

Use proper markdown formatting with code blocks.
"""
        }, {
            "role": "user",
            "content": project_summary
        }]
    )

    with open(os.path.join(repo_path, "README.md"), "w") as f:
        f.write(response.choices[0].message.content)
    print(f"Generated README.md for {project_name}")

generate_readme("./my_project")

import ast

def extract_Python_API(source_path):
    """Parse Python source to extract function signatures and docstrings."""
    with open(source_path) as f:
        tree = ast.parse(f.read())

    functions = []
    for node in ast.walk(tree):
        if isinstance(node, ast.FunctionDef):
            docstring = ast.get_docstring(node) or ""
            args = [arg.arg for arg in node.args.args]
            returns = ast.unparse(node.returns) if node.returns else "None"
            functions.append({
                "name": node.name,
                "args": args,
                "returns": returns,
                "docstring": docstring,
                "line": node.lineno
            })

    return functions

# Extract API from a module
API_functions = extract_Python_API("src/dodazip/compressor.py")

# Generate API docs using AI
API_context = "\n".join([
    f"Function: {f['name']}({', '.join(f['args'])}) -> {f['returns']}\n"
    f"Docstring: {f['docstring']}\n"
    for f in API_functions
])

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{
        "role": "system",
        "content": "Generate markdown API documentation with function signatures, ]
                   "parameter descriptions, return values, and usage examples."
    }, {
        "role": "user",
        "content": API_context
    }]
)

with open("docs/API-reference.md", "w") as f:
    f.write("# API Reference\n\n")
    f.write(response.choices[0].message.content)

import subprocess

def generate_changelog(since_tag=None, to_tag="HEAD"):
    """Generate a changelog from git commit history using AI."""

    # Get git log
    cmd = ["git", "log", "--oneline", "--format=%H|%an|%s|%ai"]
    if since_tag:
        cmd.insert(3, f"{since_tag}..{to_tag}")
    else:
        cmd.insert(3, f"--max-count=50")

    result = subprocess.run(cmd, capture_output=True, text=True)
    commits = []
    for line in result.stdout.strip().split("\n"):
        if not line:
            continue
        hash_, author, subject, date = line.split("|", 3)
        commits.append({
            "hash": hash_[:8],
            "author": author,
            "subject": subject,
            "date": date[:10]
        })

    # Format for AI
    commit_log = "\n".join([
        f"- {c['date']} | {c['author']}: {c['subject']}"
        for c in commits
    ])

    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[{
            "role": "system",
            "content": ""]
You are generating a changelog from git commits. Categorize changes into:

## Added
## Changed
## Fixed
## Deprecated
## Removed
## Security

Use the commit messages to infer the category. Combine related commits.
Use present tense, bullet points.
"""
        }, {
            "role": "user",
            "content": f"Generate a changelog from these commits:\n\n{commit_log}"
        }]
    )

    with open("CHANGELOG.md", "w") as f:
        f.write("# Changelog\n\n")
        f.write(response.choices[0].message.content)

    print(f"Generated changelog from {len(commits)} commits")

generate_changelog("v1.0.0", "v1.1.0")

def generate_docstring(source_code, function_name):
    """Generate a PEP 257 compliant docstring for a function."""
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[{
            "role": "system",
            "content": ""]
Generate a Python docstring following PEP 257 and Google style.
Include:
1. Description of what the function does
2. Args section with parameter types and descriptions
3. Returns section with type and description
4. Raises section if applicable
5. Example usage in doctest format
"""
        }, {
            "role": "user",
            "content": f"Generate docstring for this function:\n\n{source_code}"
        }]
    )
    return response.choices[0].message.content

code = """
def calculate_checksums(file_paths, algorithm='sha256'):
    results = {}
    for path in file_paths:
        import hashlib
        h = hashlib.new(algorithm)
        with open(path, 'rb') as f:
            for chunk in iter(lambda: f.read(8192), b''):
                h.update(chunk)
        results[path] = h.hexdigest()
    return results
"""

docstring = generate_docstring(code, "calculate_checksums")
full_code = f"def calculate_checksums(file_paths, algorithm='sha256'):\n"
full_code += f'    """{docstring}"""\n'
full_code += "\n".join("    " + line for line in code.split("\n")[1:])
print(full_code)

def calculate_checksums(file_paths, algorithm='sha256'):
    """Calculate cryptographic checksums for a list of files.

    Reads each file in chunks and computes the specified hash algorithm.

    Args:
        file_paths (list): List of file paths to process.
        algorithm (str): Hash algorithm to use (default: 'sha256').

    Returns:
        dict: Mapping of file paths to their hex digest strings.

    Raises:
        FileNotFoundError: If any file path does not exist.
        ValueError: If the algorithm is not supported by hashlib.

    Example:
        >>> calculate_checksums(['file1.txt', 'file2.bin'])
        {'file1.txt': 'abc123...', 'file2.bin': 'def456...'}
    """
    results = {}
    for path in file_paths:
        import hashlib
        h = hashlib.new(algorithm)
        with open(path, 'rb') as f:
            for chunk in iter(lambda: f.read(8192), b''):
                h.update(chunk)
        results[path] = h.hexdigest()
    return results

# .github/workflows/docs-automation.yml
name: Auto Documentation
on:
  push:
    branches: [main]
    paths:
      - 'src/**'
      - '!docs/**'

jobs:
  generate-docs:
    runs-on: Ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Setup Python
        uses: actions/setup-Python@v5
        with:
          Python-version: '3.12'

      - name: Install dependencies
        run: Pip install OpenAI pyyaml

      - name: Generate API docs
        run: Python scripts/generate_API_docs.py

      - name: Update README
        run: Python scripts/generate_readme.py

      - name: Generate Changelog Draft
        run: Python scripts/generate_changelog.py

      - name: Create Pull Request
        uses: peter-evans/create-pull-request@v6
        with:
          commit-message: "docs: auto-generate documentation"
          title: "docs: auto-generated documentation update"
          body: "Automated documentation update triggered by source code changes."
          Branch: docs/auto-update