代码生成文档

import requests

# DeepSeek API的URL地址（本地Ollama服务器地址）
OLLAMA_URL = "http://localhost:11434/api/generate"

def generate_readme(project_description):
    """
    根据项目描述生成README文件
    参数:
        project_description: 项目描述文本
    返回:
        str: 生成的README内容
    """
    # 构建提示词，要求AI生成README
    prompt = f"Generate a professional README file for the following project:\n\n{project_description}"

    # 设置API请求参数
    payload = {
        "model": "deepseek-r1",  # 使用deepseek-r1模型
        "prompt": prompt,         # 提示词内容
        "stream": False          # 不使用流式输出
    }

    # 发送请求并返回结果
    response = requests.post(OLLAMA_URL, json=payload)
    return response.json().get("response", "No README generated.")

def document_api(code_snippet):
    """
    生成API文档
    参数:
        code_snippet: 需要生成文档的代码片段
    返回:
        str: 生成的API文档
    """
    # 构建提示词，要求AI生成API文档
    prompt = f"Generate API documentation for the following code:\n\n{code_snippet}"

    # 设置API请求参数
    payload = {
        "model": "deepseek-r1",  # 使用deepseek-r1模型
        "prompt": prompt,         # 提示词内容
        "stream": False          # 不使用流式输出
    }

    # 发送请求并返回结果
    response = requests.post(OLLAMA_URL, json=payload)
    return response.json().get("response", "No API documentation available.")

def generate_documentation(code_snippet, language="Python"):
    """
    使用DeepSeek AI为代码生成详细文档
    参数:
        code_snippet: 需要生成文档的代码片段
        language: 编程语言，默认为Python
    返回:
        str: 生成的代码文档
    """
    # 构建提示词，要求AI生成详细文档
    prompt = f"Generate detailed documentation for the following {language} code:\n\n{code_snippet}\n\n" \
             "Add appropriate docstrings, comments, and explanations."

    # 设置API请求参数
    payload = {
        "model": "deepseek-r1",  # 使用deepseek-r1模型
        "prompt": prompt,         # 提示词内容
        "stream": False          # 不使用流式输出
    }

    # 发送请求并处理响应
    response = requests.post(OLLAMA_URL, json=payload)

    if response.status_code == 200:
        return response.json().get("response", "No documentation generated.")
    else:
        return f"Error: {response.text}"


if __name__ == "__main__":
    test_code = "def add(a, b): return a + b"
    print(generate_documentation(test_code))

~/code/genai/deepseek > /opt/homebrew/bin/python3 /Users/kpingfan/code/genai/deepseek/code-document.py       INT 1h 5m 18s
<think>
Okay, I need to generate detailed documentation for this simple Python function: def add(a, b): return a + b. The user wants me to add docstrings, comments, and explanations.

First, I should start with the function's basic information. The name is add, so the docstring should explain what it does. It takes two parameters, a and b, which can be numbers. The function returns their sum.

I remember that in Python, using type hints makes the code more readable and helps with static analysis. So I'll include : int or float for the return type too.

Next, I need to think about how to structure this into a proper docstring. It should have a module-level description if it's part of a package. Then individual docstrings for each function, parameter, returns, and maybe an example usage.

Wait, sometimes people use "Args" or "Parameters" as a header in the docstring. That makes sense because it clearly groups all the parameters together. So I'll structure the function's docstring with that approach.

For examples, it's good to show how the function is used. Like adding two integers, a float and an integer, maybe even different types like int and str if applicable, but in this case, since add only works with numbers, perhaps stick to numeric examples.

I should also mention any exceptions or edge cases. For example, what happens if someone passes more than two arguments? Oh right, the function expects exactly two, so it'll throw a TypeError automatically. So I can note that.

Putting it all together, the docstring will cover the function's purpose, parameters, return type, examples of usage, and any important notes about input constraints.

Let me outline each part:

- Module-level: Brief description.
- Function: Detailed explanation.
- Args: Parameters a and b with types.
- Returns: Return type is sum as int or float.
- Examples: Show different usages.
- Notes: Additional information like required arguments, type checks (though in code it's handled automatically).

I think that covers everything. Now I'll write each section step by step, making sure to be clear and concise.
</think>

Here is the detailed documentation for the `add` function:

```python
"""
This module provides a simple function to add two numbers.

The `add` function takes two numerical arguments and returns their sum.

Parameters:
    a (int | float): The first number to be added.
    b (int | float): The second number to be added.

Returns:
    int | float: The sum of the two input numbers.

Examples:
    >>> add(10, 5)
    15

    >>> add(3.5, 2)
    5.5

    >>> add(-1, 4)
    3

Notes:
    This function requires exactly two arguments.
    The types of `a` and `b` must be either int or float for this function to work correctly.
"""

def add(a: int | float, b: int | float) -> int | float:
    """
    Adds two numbers.

    Args:
        a (int | float): The first number to add.
        b (int | float): The second number to add.

    Returns:
        int | float: The sum of the two numbers.
    """
    return a + b
```

### Explanation

- **Module-level**: Briefly explains what this module does, specifically mentioning that it provides an `add` function for adding two numerical values.

- **Function Documentation** (`add`):
  - **Parameters**: Describes each parameter with its expected type.
  - **Returns**: Specifies the return type and whether it's a sum of integers or floats.

- **Examples**:
  - Provides clear examples showing how to use the function with different numeric types, demonstrating that it works correctly for various inputs.

- **Notes**:
  - Additional information about required arguments and expected input types ensures users understand the constraints when using this function.

import requests
import gradio as gr
# DeepSeek API的URL地址（本地Ollama服务器地址）
OLLAMA_URL = "http://localhost:11434/api/generate"

def generate_readme(project_description):
    """
    根据项目描述生成README文件
    参数:
        project_description: 项目描述文本
    返回:
        str: 生成的README内容
    """
    # 构建提示词，要求AI生成README
    prompt = f"Generate a professional README file for the following project:\n\n{project_description}"

    # 设置API请求参数
    payload = {
        "model": "deepseek-r1",  # 使用deepseek-r1模型
        "prompt": prompt,         # 提示词内容
        "stream": False          # 不使用流式输出
    }

    # 发送请求并返回结果
    response = requests.post(OLLAMA_URL, json=payload)
    return response.json().get("response", "No README generated.")

def document_api(code_snippet):
    """
    生成API文档
    参数:
        code_snippet: 需要生成文档的代码片段
    返回:
        str: 生成的API文档
    """
    # 构建提示词，要求AI生成API文档
    prompt = f"Generate API documentation for the following code:\n\n{code_snippet}"

    # 设置API请求参数
    payload = {
        "model": "deepseek-r1",  # 使用deepseek-r1模型
        "prompt": prompt,         # 提示词内容
        "stream": False          # 不使用流式输出
    }

    # 发送请求并返回结果
    response = requests.post(OLLAMA_URL, json=payload)
    return response.json().get("response", "No API documentation available.")

def generate_documentation(code_snippet, language="Python"):
    """
    使用DeepSeek AI为代码生成详细文档
    参数:
        code_snippet: 需要生成文档的代码片段
        language: 编程语言，默认为Python
    返回:
        str: 生成的代码文档
    """
    # 构建提示词，要求AI生成详细文档
    prompt = f"Generate detailed documentation for the following {language} code:\n\n{code_snippet}\n\n" \
             "Add appropriate docstrings, comments, and explanations."

    # 设置API请求参数
    payload = {
        "model": "deepseek-r1",  # 使用deepseek-r1模型
        "prompt": prompt,         # 提示词内容
        "stream": False          # 不使用流式输出
    }

    # 发送请求并处理响应
    response = requests.post(OLLAMA_URL, json=payload)

    if response.status_code == 200:
        return response.json().get("response", "No documentation generated.")
    else:
        return f"Error: {response.text}"


# 创建Gradio界面
interface = gr.Interface(
    fn=generate_documentation,  # 指定处理函数
    inputs=[  # 定义输入组件
        gr.Textbox(lines=10, placeholder="在此粘贴您的代码"),  # 多行文本框用于输入代码
        gr.Dropdown(["Python", "JavaScript", "Java", "C++"], label="选择编程语言"),  # 下拉菜单选择语言
    ],
    outputs=gr.Textbox(label="AI生成的文档"),  # 输出组件:显示AI生成的文档
    title="AI驱动的文档生成器",  # 界面标题
    description="粘贴您的代码，AI将生成详细的文档说明。"  # 界面描述文本
)

# 启动Web应用
if __name__ == "__main__":
    interface.launch()