Python生成Markdown文件的完整指南_Python

一、基础方法：直接写入

1. 简单文本写入

def create_simple_markdown():
    """创建简单的markdown文件"""
    
    content = """# 主标题

这是第一个段落。

## 二级标题

这是第二个段落。

### 三级标题

这是一个无序列表：
- 项目1
- 项目2
- 项目3

这是一个有序列表：
1. 第一项
2. 第二项
3. 第三项

**粗体文本** 和 *斜体文本*

`行内代码`

[链接文本](https://example.com)

![图片描述](image.jpg)
"""
    
    with open("simple_document.md", "w", encoding="utf-8") as f:
        f.write(content)
    
    print("markdown文件已创建: simple_document.md")

# 使用
create_simple_markdown()

2. 动态生成内容

def create_dynamic_markdown(data):
    """根据数据动态生成markdown"""
    
    content = f"""# {data['title']}

**创建时间**: {data['date']}
**作者**: {data['author']}

## 概述
{data['overview']}

## 详细内容
{data['content']}

## 特性
"""
    
    # 添加列表
    for feature in data['features']:
        content += f"- {feature}\n"
    
    content += f"""
## 代码示例
```python
{data['code_example']}

总结

with open("dynamic_document.md", "w", encoding="utf-8") as f:
    f.write(content)

print("动态markdown文件已创建")

使用示例

data = {
‘title': ‘python项目文档',
‘date': ‘2024-01-20',
‘author': ‘张三',
‘overview': ‘这是一个使用python生成markdown的示例项目。',
‘content': ‘详细说明了如何使用python创建markdown文件。',
‘features': [
‘自动生成文档',
‘支持多种格式',
‘可自定义模板',
‘易于扩展'
],
‘code_example': ‘print(“hello, markdown!”)',
‘summary': ‘这是一个非常有用的工具。'
}

create_dynamic_markdown(data)

二、使用模板引擎生成

1. 使用字符串模板

#python
from string import template

class markdowntemplate:
    """markdown模板生成器"""
    
    def __init__(self):
        self.templates = {
            'report': self._report_template(),
            'api_doc': self._api_doc_template(),
            'readme': self._readme_template(),
            'note': self._note_template()
        }
    
    def _report_template(self):
        """报告模板"""
        return template("""# ${title}

## 基本信息
- **项目**: ${project}
- **日期**: ${date}
- **作者**: ${author}
- **版本**: ${version}

## 执行摘要
${summary}

## 详细内容
${content}

## 结果分析
${analysis}

## 结论
${conclusion}

## 建议
${recommendations}

## 附录
${appendix}
""")
    
    def _readme_template(self):
        """readme模板"""
        return template("""# ${project_name}

${badges}

${description}

## ✨ 特性
${features}

## 🚀 快速开始

### 安装
\`\`\`bash
${install_command}
\`\`\`

### 使用示例
\`\`\`python
${usage_example}
\`\`\`

## 📖 文档
${documentation}

## 🤝 贡献
${contributing}

## 📄 许可证
${license}

## 📞 联系方式
${contact}
""")
    
    def _api_doc_template(self):
        """api文档模板"""
        return template("""# ${api_name} api 文档

## 概述
${overview}

## 认证
${authentication}

## 端点

### ${endpoint_name}
**url**: \`${url}\`

**方法**: ${method}

**参数**:
${parameters}

**响应**:
\`\`\`json
${response_example}
\`\`\`

**错误码**:
${error_codes}

## 使用示例
${usage_examples}
""")
    
    def generate(self, template_name, data, output_file=none):
        """生成markdown文件"""
        if template_name not in self.templates:
            raise valueerror(f"模板不存在: {template_name}")
        
        template = self.templates[template_name]
        content = template.safe_substitute(data)
        
        if output_file:
            with open(output_file, "w", encoding="utf-8") as f:
                f.write(content)
            print(f"markdown文件已生成: {output_file}")
        
        return content

# 使用示例
md_generator = markdowntemplate()

# 生成报告
report_data = {
    'title': '季度项目报告',
    'project': '数据分析平台',
    'date': '2024-q1',
    'author': '张三',
    'version': '1.0.0',
    'summary': '本季度项目进展顺利，完成了主要功能开发。',
    'content': '详细开发了数据导入、处理和可视化模块。',
    'analysis': '性能提升了30%，用户满意度达到95%。',
    'conclusion': '项目按计划推进，达到预期目标。',
    'recommendations': '建议增加ai分析功能。',
    'appendix': '详见附件文档。'
}

report_md = md_generator.generate('report', report_data, '季度报告.md')

# 生成readme
readme_data = {
    'project_name': 'awesome project',
    'badges': '[![python version](https://img.shields.io/badge/python-3.8+-blue.svg)]',
    'description': '一个非常棒的项目，用于演示markdown生成。',
    'features': '- 功能一\n- 功能二\n- 功能三',
    'install_command': 'pip install awesome-project',
    'usage_example': 'from awesome import awesome\nobj = awesome()\nobj.do_something()',
    'documentation': '详见 [文档网站](https://docs.example.com)',
    'contributing': '欢迎提交pr！',
    'license': 'mit license',
    'contact': '邮箱: contact@example.com'
}

readme_md = md_generator.generate('readme', readme_data, 'readme.md')

2. 使用 jinja2 模板引擎

from jinja2 import template, environment, filesystemloader
import os

class jinjamarkdowngenerator:
    """使用jinja2生成markdown"""
    
    def __init__(self, template_dir="templates"):
        self.env = environment(
            loader=filesystemloader(template_dir),
            trim_blocks=true,
            lstrip_blocks=true,
            keep_trailing_newline=true
        )
    
    def generate_from_template(self, template_name, context, output_file):
        """从模板生成markdown"""
        template = self.env.get_template(template_name)
        content = template.render(**context)
        
        with open(output_file, "w", encoding="utf-8") as f:
            f.write(content)
        
        print(f"markdown文件已生成: {output_file}")
        return content

# 创建模板目录和文件
os.makedirs("templates", exist_ok=true)

# 创建report模板 (templates/report.md.j2)
report_template_content = """# {{ title }}

## 项目信息
- **项目名称**: {{ project_name }}
- **版本**: v{{ version }}
- **生成时间**: {{ generated_at }}

## 概述
{{ overview }}

## 详细分析
{% for section in sections %}
### {{ section.title }}
{{ section.content }}

{% if section.items %}
**关键点**:
{% for item in section.items %}
- {{ item }}
{% endfor %}
{% endif %}

{% endfor %}

## 数据统计
| 指标 | 数值 | 状态 |
|------|------|------|
{% for metric in metrics %}
| {{ metric.name }} | {{ metric.value }} | {{ metric.status }} |
{% endfor %}

## 代码示例
```{{ code_language }}
{{ code_example }}

总结

with open(“templates/report.md.j2”, “w”, encoding=“utf-8”) as f:
f.write(report_template_content)

使用jinja2生成

generator = jinjamarkdowngenerator(“templates”)

context = {
‘title': ‘项目分析报告',
‘project_name': ‘数据分析系统',
‘version': ‘1.2.0',
‘generated_at': ‘2024-01-20 10:30:00',
‘overview': ‘本报告分析了系统的运行情况和性能指标。',
‘sections': [
{
‘title': ‘性能分析',
‘content': ‘系统性能良好，响应时间在预期范围内。',
‘items': [‘平均响应时间: 200ms', ‘吞吐量: 1000 req/s', ‘错误率: 0.1%']
},
{
‘title': ‘用户分析',
‘content': ‘用户活跃度持续增长。',
‘items': [‘日活用户: 10,000', ‘月活用户: 50,000', ‘用户留存率: 85%']
}
],
‘metrics': [
{‘name': ‘cpu使用率', ‘value': ‘45%', ‘status': ‘正常'},
{‘name': ‘内存使用率', ‘value': ‘60%', ‘status': ‘正常'},
{‘name': ‘磁盘空间', ‘value': ‘75%', ‘status': ‘警告'},
{‘name': ‘网络延迟', ‘value': ‘50ms', ‘status': ‘优秀'}
],
‘code_language': ‘python',
‘code_example': ‘def analyze_data(data):\n return process(data)',
‘summary': ‘系统运行稳定，建议关注磁盘空间使用情况。'
}

generator.generate_from_template(
‘report.md.j2',
context,
‘项目分析报告.md'
)

三、使用专业库生成

1. 使用 python-markdown 库（反向生成）

#python
import markdown
from markdown.extensions.toc import tocextension
from markdown.extensions.codehilite import codehiliteextension
from markdown.extensions.tables import tableextension

class markdowngenerator:
    """高级markdown生成器"""
    
    def __init__(self):
        self.elements = []
    
    def add_title(self, text, level=1):
        """添加标题"""
        prefix = '#' * level
        self.elements.append(f"{prefix} {text}\n")
        return self
    
    def add_paragraph(self, text):
        """添加段落"""
        self.elements.append(f"{text}\n\n")
        return self
    
    def add_list(self, items, ordered=false):
        """添加列表"""
        for i, item in enumerate(items):
            if ordered:
                self.elements.append(f"{i+1}. {item}\n")
            else:
                self.elements.append(f"- {item}\n")
        self.elements.append("\n")
        return self
    
    def add_code_block(self, code, language=""):
        """添加代码块"""
        self.elements.append(f"```{language}\n[code]\n```\n\n")
        return self
    
    def add_table(self, headers, rows):
        """添加表格"""
        # 表头
        header_row = "| " + " | ".join(headers) + " |"
        separator = "| " + " | ".join(["---"] * len(headers)) + " |"
        
        self.elements.append(header_row + "\n")
        self.elements.append(separator + "\n")
        
        # 数据行
        for row in rows:
            row_str = "| " + " | ".join(str(cell) for cell in row) + " |"
            self.elements.append(row_str + "\n")
        
        self.elements.append("\n")
        return self
    
    def add_blockquote(self, text):
        """添加引用"""
        lines = text.split('\n')
        for line in lines:
            self.elements.append(f"> {line}\n")
        self.elements.append("\n")
        return self
    
    def add_horizontal_rule(self):
        """添加水平线"""
        self.elements.append("---\n\n")
        return self
    
    def add_link(self, text, url):
        """添加链接"""
        self.elements.append(f"[{text}]({url})\n\n")
        return self
    
    def add_image(self, alt_text, url, title=""):
        """添加图片"""
        if title:
            self.elements.append(f'![{alt_text}]({url} "{title}")\n\n')
        else:
            self.elements.append(f'![{alt_text}]({url})\n\n')
        return self
    
    def generate(self, output_file=none):
        """生成markdown内容"""
        content = "".join(self.elements)
        
        if output_file:
            with open(output_file, "w", encoding="utf-8") as f:
                f.write(content)
            print(f"markdown文件已生成: {output_file}")
        
        return content

# 使用示例
md = markdowngenerator()

md.add_title("python学习笔记", level=1)
md.add_paragraph("这是我的python学习笔记，记录了一些重要的概念和示例。")
md.add_horizontal_rule()

md.add_title("基本语法", level=2)
md.add_paragraph("python的基本语法非常简洁。")

md.add_title("数据类型", level=3)
md.add_list([
    "整数 (int)",
    "浮点数 (float)",
    "字符串 (str)",
    "列表 (list)",
    "字典 (dict)"
])

md.add_title("代码示例", level=2)
md.add_code_block("def hello(name):\n    print(f'hello, {name}!')\n\nhello('world')", "python")

md.add_title("数据结构对比", level=2)
md.add_table(
    ["数据结构", "可变性", "有序性", "示例"],
    [
        ["列表", "可变", "有序", "[1, 2, 3]"],
        ["元组", "不可变", "有序", "(1, 2, 3)"],
        ["集合", "可变", "无序", "{1, 2, 3}"],
        ["字典", "可变", "有序(3.7+)", "{'a': 1, 'b': 2}"]
    ]
)

md.add_blockquote("python之禅：优美胜于丑陋，明了胜于晦涩。")

md.add_title("参考资源", level=2)
md.add_link("python官方文档", "https://docs.python.org")
md.add_image("python logo", "https://www.python.org/static/img/python-logo.png", "python官方logo")

# 生成文件
content = md.generate("学习笔记.md")

2. 使用 mistune 库

import mistune

class markdownrenderer(mistune.htmlrenderer):
    """自定义markdown渲染器（可用于反向生成）"""
    
    def __init__(self, escape=true):
        super().__init__(escape)
        self.output = []
    
    def text(self, text):
        self.output.append(text)
        return text
    
    def paragraph(self, text):
        self.output.append(f"\n{text}\n")
        return f"<p>{text}</p>"
    
    def generate_markdown(self):
        """获取生成的markdown内容"""
        return "".join(self.output)

# 使用mistune解析并生成
def convert_to_markdown(html_content):
    """将html转换为markdown（简单示例）"""
    # 注意：mistune主要是html转markdown，这里展示反向思路
    pass

四、从数据结构生成

1. 从json/yaml生成

import json
import yaml
from typing import dict, list, any

class datatomarkdown:
    """从数据结构生成markdown"""
    
    def __init__(self, indent_size=2):
        self.indent_size = indent_size
        self.indent_char = ' '
    
    def from_json(self, json_file: str, output_file: str = none) -> str:
        """从json文件生成markdown"""
        with open(json_file, 'r', encoding='utf-8') as f:
            data = json.load(f)
        
        return self._generate_from_dict(data, output_file)
    
    def from_yaml(self, yaml_file: str, output_file: str = none) -> str:
        """从yaml文件生成markdown"""
        with open(yaml_file, 'r', encoding='utf-8') as f:
            data = yaml.safe_load(f)
        
        return self._generate_from_dict(data, output_file)
    
    def from_dict(self, data: dict, output_file: str = none) -> str:
        """从字典生成markdown"""
        return self._generate_from_dict(data, output_file)
    
    def _generate_from_dict(self, data: dict, output_file: str = none) -> str:
        """从字典生成markdown内容"""
        lines = []
        
        def process_value(key, value, level=0):
            indent = self.indent_char * self.indent_size * level
            
            if isinstance(value, dict):
                # 标题
                lines.append(f"{indent}# {' '.join(key.split('_')).title()}\n")
                
                # 处理字典的键值对
                for k, v in value.items():
                    if isinstance(v, (dict, list)):
                        process_value(k, v, level + 1)
                    else:
                        lines.append(f"{indent}- **{k.replace('_', ' ').title()}**: {v}\n")
                lines.append("\n")
            
            elif isinstance(value, list):
                # 列表标题
                lines.append(f"{indent}## {' '.join(key.split('_')).title()}\n")
                
                for item in value:
                    if isinstance(item, dict):
                        lines.append(f"{indent}###\n")
                        for k, v in item.items():
                            lines.append(f"{indent}- **{k.replace('_', ' ').title()}**: {v}\n")
                    else:
                        lines.append(f"{indent}- {item}\n")
                lines.append("\n")
            
            else:
                # 简单键值对
                lines.append(f"{indent}- **{key.replace('_', ' ').title()}**: {value}\n")
        
        # 开始处理
        if isinstance(data, dict):
            # 添加主标题
            title = data.get('title', 'document')
            lines.append(f"# {title}\n\n")
            
            # 处理其他内容
            for key, value in data.items():
                if key != 'title':
                    process_value(key, value)
        else:
            lines.append("# document\n\n")
            process_value('content', data)
        
        # 合并所有行
        content = ''.join(lines)
        
        # 写入文件
        if output_file:
            with open(output_file, 'w', encoding='utf-8') as f:
                f.write(content)
            print(f"markdown文件已生成: {output_file}")
        
        return content

# 使用示例
json_data = {
    "title": "api 配置文档",
    "metadata": {
        "version": "1.0.0",
        "author": "张三",
        "created_at": "2024-01-20"
    },
    "endpoints": [
        {
            "name": "获取用户信息",
            "method": "get",
            "path": "/api/users/{id}",
            "description": "根据用户id获取用户信息",
            "parameters": [
                {"name": "id", "type": "integer", "required": true}
            ],
            "responses": [
                {"code": 200, "description": "成功"},
                {"code": 404, "description": "用户不存在"}
            ]
        },
        {
            "name": "创建用户",
            "method": "post",
            "path": "/api/users",
            "description": "创建新用户",
            "parameters": [
                {"name": "username", "type": "string", "required": true},
                {"name": "email", "type": "string", "required": true}
            ],
            "responses": [
                {"code": 201, "description": "用户创建成功"},
                {"code": 400, "description": "参数错误"}
            ]
        }
    ],
    "authentication": {
        "type": "jwt",
        "description": "需要在请求头中添加authorization: bearer <token>"
    }
}

# 从字典生成
converter = datatomarkdown()
markdown_content = converter.from_dict(json_data, "api_docs.md")

# 或者从json文件生成
with open("config.json", "w", encoding="utf-8") as f:
    json.dump(json_data, f, ensure_ascii=false, indent=2)

converter.from_json("config.json", "api_docs_from_json.md")

2. 从数据库生成文档

import sqlite3
import mysql.connector
from typing import list, dict

class databasetomarkdown:
    """从数据库生成markdown文档"""
    
    def __init__(self, db_type='sqlite', **kwargs):
        self.db_type = db_type
        self.connection_params = kwargs
        
    def connect(self):
        """连接到数据库"""
        if self.db_type == 'sqlite':
            self.conn = sqlite3.connect(self.connection_params.get('database'))
        elif self.db_type == 'mysql':
            self.conn = mysql.connector.connect(**self.connection_params)
        else:
            raise valueerror(f"不支持的数据库类型: {self.db_type}")
        
        return self.conn
    
    def generate_schema_doc(self, output_file: str = none) -> str:
        """生成数据库模式文档"""
        self.connect()
        cursor = self.conn.cursor()
        
        lines = ["# 数据库模式文档\n\n"]
        
        # 获取所有表
        if self.db_type == 'sqlite':
            cursor.execute("select name from sqlite_master where type='table';")
            tables = [row[0] for row in cursor.fetchall()]
        elif self.db_type == 'mysql':
            cursor.execute("show tables;")
            tables = [row[0] for row in cursor.fetchall()]
        
        for table in tables:
            if table.startswith('sqlite_'):
                continue
            
            lines.append(f"## 表: `{table}`\n\n")
            
            # 获取表结构
            if self.db_type == 'sqlite':
                cursor.execute(f"pragma table_info({table});")
                columns = cursor.fetchall()
                
                # 表头
                lines.append("| 字段名 | 类型 | 是否为空 | 默认值 | 主键 |\n")
                lines.append("|--------|------|----------|--------|------|\n")
                
                for col in columns:
                    col_id, name, type_, notnull, default, pk = col
                    lines.append(f"| {name} | {type_} | {'not null' if notnull else ''} | {default if default else ''} | {'✓' if pk else ''} |\n")
            
            elif self.db_type == 'mysql':
                cursor.execute(f"describe {table};")
                columns = cursor.fetchall()
                
                lines.append("| 字段名 | 类型 | 是否为空 | 键 | 默认值 | 额外 |\n")
                lines.append("|--------|------|----------|----|--------|------|\n")
                
                for col in columns:
                    lines.append(f"| {col[0]} | {col[1]} | {col[2]} | {col[3]} | {col[4]} | {col[5]} |\n")
            
            lines.append("\n")
            
            # 获取索引信息
            if self.db_type == 'sqlite':
                cursor.execute(f"pragma index_list({table});")
                indexes = cursor.fetchall()
                
                if indexes:
                    lines.append("### 索引\n\n")
                    for idx in indexes:
                        idx_id, idx_name, unique = idx
                        lines.append(f"- **{idx_name}** ({'唯一' if unique else '非唯一'})\n")
                    lines.append("\n")
            
            # 获取外键信息
            if self.db_type == 'sqlite':
                cursor.execute(f"pragma foreign_key_list({table});")
                foreign_keys = cursor.fetchall()
                
                if foreign_keys:
                    lines.append("### 外键约束\n\n")
                    for fk in foreign_keys:
                        lines.append(f"- 从 `{fk[3]}` 到 `{fk[2]}.{fk[4]}`\n")
                    lines.append("\n")
        
        # 关闭连接
        cursor.close()
        self.conn.close()
        
        content = "".join(lines)
        
        if output_file:
            with open(output_file, "w", encoding="utf-8") as f:
                f.write(content)
            print(f"数据库文档已生成: {output_file}")
        
        return content
    
    def generate_data_dictionary(self, output_file: str = none) -> str:
        """生成数据字典"""
        self.connect()
        cursor = self.conn.cursor()
        
        lines = ["# 数据字典\n\n"]
        
        # 获取所有表
        if self.db_type == 'sqlite':
            cursor.execute("select name from sqlite_master where type='table';")
            tables = [row[0] for row in cursor.fetchall()]
        elif self.db_type == 'mysql':
            cursor.execute("show tables;")
            tables = [row[0] for row in cursor.fetchall()]
        
        for table in tables:
            if table.startswith('sqlite_'):
                continue
            
            lines.append(f"## `{table}`\n\n")
            lines.append("### 描述\n\n[填写表描述]\n\n")
            
            lines.append("### 字段说明\n\n")
            lines.append("| 字段名 | 数据类型 | 描述 | 示例 | 约束 |\n")
            lines.append("|--------|----------|------|------|------|\n")
            
            # 获取字段信息
            if self.db_type == 'sqlite':
                cursor.execute(f"pragma table_info({table});")
                columns = cursor.fetchall()
                
                for col in columns:
                    col_id, name, type_, notnull, default, pk = col
                    constraints = []
                    if pk:
                        constraints.append("主键")
                    if notnull:
                        constraints.append("非空")
                    if default:
                        constraints.append(f"默认值: {default}")
                    
                    lines.append(f"| {name} | {type_} | [填写描述] | [填写示例] | {', '.join(constraints)} |\n")
            
            elif self.db_type == 'mysql':
                cursor.execute(f"describe {table};")
                columns = cursor.fetchall()
                
                for col in columns:
                    name, type_, nullable, key, default, extra = col
                    constraints = []
                    if key == 'pri':
                        constraints.append("主键")
                    if key == 'uni':
                        constraints.append("唯一")
                    if nullable == 'no':
                        constraints.append("非空")
                    if default:
                        constraints.append(f"默认值: {default}")
                    if extra:
                        constraints.append(extra)
                    
                    lines.append(f"| {name} | {type_} | [填写描述] | [填写示例] | {', '.join(constraints)} |\n")
            
            lines.append("\n### 业务规则\n\n[填写业务规则]\n\n")
            lines.append("### 使用示例\n\n```sql\nselect * from {table} limit 5;\n```\n\n")
            lines.append("---\n\n")
        
        cursor.close()
        self.conn.close()
        
        content = "".join(lines)
        
        if output_file:
            with open(output_file, "w", encoding="utf-8") as f:
                f.write(content)
            print(f"数据字典已生成: {output_file}")
        
        return content

# 使用示例
# 创建测试数据库
conn = sqlite3.connect(":memory:")
cursor = conn.cursor()

cursor.execute("""
create table users (
    id integer primary key,
    username text not null unique,
    email text not null,
    created_at timestamp default current_timestamp
);
""")

cursor.execute("""
create table posts (
    id integer primary key,
    user_id integer,
    title text not null,
    content text,
    created_at timestamp default current_timestamp,
    foreign key (user_id) references users(id)
);
""")

conn.commit()
conn.close()

# 生成文档
doc_gen = databasetomarkdown(db_type='sqlite', database=":memory:")
schema_doc = doc_gen.generate_schema_doc("数据库模式.md")
data_dict = doc_gen.generate_data_dictionary("数据字典.md")

五、高级功能：自动生成工具

1. 从python代码生成文档

import ast
import inspect
from typing import list, dict, any
import os

class pythontomarkdown:
    """从python代码生成markdown文档"""
    
    def __init__(self):
        self.imports = []
        self.classes = []
        self.functions = []
    
    def analyze_file(self, filepath: str):
        """分析python文件"""
        with open(filepath, 'r', encoding='utf-8') as f:
            content = f.read()
        
        tree = ast.parse(content)
        
        for node in ast.walk(tree):
            if isinstance(node, ast.import):
                for alias in node.names:
                    self.imports.append(alias.name)
            elif isinstance(node, ast.importfrom):
                for alias in node.names:
                    self.imports.append(f"{node.module}.{alias.name}")
            elif isinstance(node, ast.classdef):
                class_info = self._extract_class_info(node)
                self.classes.append(class_info)
            elif isinstance(node, ast.functiondef):
                # 排除类中的方法
                if not self._is_method(node):
                    func_info = self._extract_function_info(node)
                    self.functions.append(func_info)
    
    def _is_method(self, node: ast.functiondef) -> bool:
        """检查是否是类方法"""
        parent = node.parent if hasattr(node, 'parent') else none
        return isinstance(parent, ast.classdef)
    
    def _extract_class_info(self, node: ast.classdef) -> dict:
        """提取类信息"""
        class_info = {
            'name': node.name,
            'docstring': ast.get_docstring(node),
            'methods': [],
            'bases': [ast.unparse(base) for base in node.bases]
        }
        
        # 提取方法
        for item in node.body:
            if isinstance(item, ast.functiondef):
                method_info = self._extract_function_info(item)
                class_info['methods'].append(method_info)
        
        return class_info
    
    def _extract_function_info(self, node: ast.functiondef) -> dict:
        """提取函数信息"""
        func_info = {
            'name': node.name,
            'docstring': ast.get_docstring(node),
            'args': self._extract_arguments(node.args),
            'returns': ast.unparse(node.returns) if node.returns else none,
            'decorators': [ast.unparse(decorator) for decorator in node.decorator_list]
        }
        return func_info
    
    def _extract_arguments(self, args: ast.arguments) -> list[dict]:
        """提取参数信息"""
        arguments = []
        
        # 位置参数
        for arg in args.args:
            arguments.append({
                'name': arg.arg,
                'type': arg.annotation,
                'default': none
            })
        
        # 默认参数
        for i, default in enumerate(args.defaults):
            idx = len(args.args) - len(args.defaults) + i
            arguments[idx]['default'] = ast.unparse(default)
        
        # 可变参数
        if args.vararg:
            arguments.append({
                'name': f"*{args.vararg.arg}",
                'type': args.vararg.annotation,
                'default': none
            })
        
        # 关键字参数
        for kwonlyarg in args.kwonlyargs:
            arguments.append({
                'name': kwonlyarg.arg,
                'type': kwonlyarg.annotation,
                'default': none
            })
        
        # 关键字默认值
        for i, default in enumerate(args.kw_defaults):
            if default:
                arguments[len(args.args) + (1 if args.vararg else 0) + i]['default'] = ast.unparse(default)
        
        # 关键字可变参数
        if args.kwarg:
            arguments.append({
                'name': f"**{args.kwarg.arg}",
                'type': args.kwarg.annotation,
                'default': none
            })
        
        return arguments
    
    def generate_documentation(self, output_file: str = none) -> str:
        """生成文档"""
        lines = ["# api 文档\n\n"]
        
        # 导入部分
        if self.imports:
            lines.append("## 导入\n\n")
            lines.append("```python\n")
            for imp in sorted(set(self.imports)):
                if '.' in imp:
                    module, name = imp.rsplit('.', 1)
                    lines.append(f"from {module} import {name}\n")
                else:
                    lines.append(f"import {imp}\n")
            lines.append("```\n\n")
        
        # 函数部分
        if self.functions:
            lines.append("## 函数\n\n")
            for func in self.functions:
                lines.append(f"### `{func['name']}`\n\n")
                
                if func['docstring']:
                    lines.append(f"{func['docstring']}\n\n")
                
                # 函数签名
                arg_strs = []
                for arg in func['args']:
                    arg_str = arg['name']
                    if arg['type']:
                        arg_str += f": {ast.unparse(arg['type'])}"
                    if arg['default']:
                        arg_str += f" = {arg['default']}"
                    arg_strs.append(arg_str)
                
                signature = f"def {func['name']}({', '.join(arg_strs)})"
                if func['returns']:
                    signature += f" -> {func['returns']}"
                
                lines.append(f"```python\n{signature}\n```\n\n")
        
        # 类部分
        if self.classes:
            lines.append("## 类\n\n")
            for cls in self.classes:
                lines.append(f"### `{cls['name']}`\n\n")
                
                if cls['bases']:
                    lines.append(f"**继承自**: {', '.join(cls['bases'])}\n\n")
                
                if cls['docstring']:
                    lines.append(f"{cls['docstring']}\n\n")
                
                # 类的方法
                if cls['methods']:
                    lines.append("#### 方法\n\n")
                    for method in cls['methods']:
                        lines.append(f"##### `{method['name']}`\n\n")
                        
                        if method['docstring']:
                            lines.append(f"{method['docstring']}\n\n")
        
        content = "".join(lines)
        
        if output_file:
            with open(output_file, "w", encoding="utf-8") as f:
                f.write(content)
            print(f"api文档已生成: {output_file}")
        
        return content

# 使用示例
# 创建一个示例python文件
sample_code = '''
"""示例模块"""

import os
from typing import list, optional

def greet(name: str, greeting: str = "hello") -> str:
    """生成问候语
    
    args:
        name: 姓名
        greeting: 问候语，默认为'hello'
    
    returns:
        完整的问候字符串
    """
    return f"{greeting}, {name}!"

class calculator:
    """计算器类"""
    
    def __init__(self, precision: int = 2):
        """初始化计算器
        
        args:
            precision: 计算精度
        """
        self.precision = precision
    
    def add(self, a: float, b: float) -> float:
        """加法运算"""
        return round(a + b, self.precision)
    
    def multiply(self, a: float, b: float) -> float:
        """乘法运算"""
        return round(a * b, self.precision)
'''

with open("sample_module.py", "w", encoding="utf-8") as f: