3min手搓一个帮助文档，很合理吧！
作为一名全栈工程师，我经常需要在项目中快速生成帮助文档。无论是给用户参考的 README，还是给开发人员用的 API 文档，手动写 Markdown 太慢，用工具又太重。其实，3 分钟就能用手搓一个帮助文档生成器 ，高效又灵活，今天我就带你实战一把。## 为什么需要手搓帮助文档？很多项目初期，团队没有预算上 Sphinx 或 GitBook，或者文档需求很简单------只是把代码中的注释提取出来，生成一个结构化的文档。手搓的优势在于：- 零依赖 ：只需 Python 标准库，不用装任何第三方包。- 可定制 ：想输出 Markdown、HTML 还是 JSON，改几行代码就行。- 速度快 ：3 分钟从零到能跑，适合快速原型。下面，我们从两个实战场景出发，用代码演示如何"手搓"文档。## 场景一：从 Python 注释生成 Markdown 文档假设你写了一个简单的工具库 calc_helper.py，里面有几个函数，你想自动提取它们的文档字符串（docstring），生成一个 help.md 文件。### 代码示例 1：自动提取 docstring 生成 Markdownpython# file: doc_generator.pyimport osimport inspectimport importlib.utildef extract_docstrings_from_module(module_path): """ 从指定 Python 模块文件中提取所有函数和类的文档字符串。 参数: module_path (str): 模块文件路径，例如 "./calc_helper.py" 返回: dict: 包含模块名、函数名及其文档字符串的字典 """ # 动态加载模块 spec = importlib.util.spec_from_file_location("module", module_path) module = importlib.util.module_from_spec(spec) spec.loader.exec_module(module) docs = { "module_name": os.path.basename(module_path), "functions": [], "classes": [] } # 遍历模块成员 for name, obj in inspect.getmembers(module): if inspect.isfunction(obj) and obj.__module__ == module.__name__: # 提取函数文档 doc = obj.__doc__ or "（无文档）" docs["functions"].append({ "name": name, "doc": doc.strip() }) elif inspect.isclass(obj) and obj.__module__ == module.__name__: # 提取类文档 doc = obj.__doc__ or "（无文档）" docs["classes"].append({ "name": name, "doc": doc.strip() }) return docsdef generate_markdown(docs): """ 将文档字典转换为 Markdown 格式字符串。 参数: docs (dict): 由 extract_docstrings_from_module 返回的文档字典 返回: str: Markdown 格式的文档内容 """ md = f"# {docs['module_name']} 帮助文档\n\n" if docs["functions"]: md += "## 函数\n\n" for func in docs["functions"]: md += f"### `{func['name']}`\n\n{func['doc']}\n\n" if docs["classes"]: md += "## 类\n\n" for cls in docs["classes"]: md += f"### `{cls['name']}`\n\n{cls['doc']}\n\n" return md# 测试运行if __name__ == "__main__": # 假设我们要提取当前目录下的 calc_helper.py 的文档 module_file = "./calc_helper.py" if not os.path.exists(module_file): # 如果文件不存在，创建一个示例模块用于演示 with open(module_file, "w") as f: f.write('''"""一个简单的计算器辅助模块"""def add(a, b): """返回两个数的和""" return a + bdef subtract(a, b): """返回两个数的差""" return a - bclass Calculator: """一个简单的计算器类，支持加法和减法""" def multiply(self, a, b): """返回两个数的积（但这里我们只演示文档继承）""" return a * b''') docs = extract_docstrings_from_module(module_file) markdown_content = generate_markdown(docs) # 写入 Markdown 文件 with open("help.md", "w", encoding="utf-8") as f: f.write(markdown_content) print("帮助文档已生成：help.md") print(markdown_content)运行结果 ：执行 python doc_generator.py，你会发现同目录下生成了一个 help.md，内容清晰列出了函数和类的文档。整个过程不到 1 分钟。## 场景二：从 JSON 数据生成 HTML 帮助页面有时候文档数据已经存在，比如来自 API 的响应或配置文件。我们可以用 Python 快速解析 JSON 并生成一个漂亮的 HTML 页面，方便在浏览器中查看。### 代码示例 2：JSON 转 HTML 帮助页面python# file: json_to_html.pyimport jsonimport osdef load_docs_from_json(json_path): """ 从 JSON 文件加载文档数据。 JSON 格式示例： { "title": "API 帮助文档", "sections": [ {"heading": "用户接口", "content": "用于用户管理的 API 端点"}, {"heading": "订单接口", "content": "用于订单处理的 API 端点"} ] } 参数: json_path (str): JSON 文件路径 返回: dict: 文档数据字典 """ with open(json_path, "r", encoding="utf-8") as f: return json.load(f)def generate_html(doc_data): """ 根据文档数据生成完整的 HTML 页面。 参数: doc_data (dict): 包含 title 和 sections 的字典 返回: str: HTML 字符串 """ title = doc_data.get("title", "帮助文档") sections = doc_data.get("sections", []) # 构建 HTML 结构（使用内联样式，避免外部依赖） html_parts = [ "<!DOCTYPE html>", "<html lang='zh-CN'>", "<head>", f"<meta charset='UTF-8'>", f"<title>{title}</title>", "<style>", "body { font-family: Arial, sans-serif; max-width: 800px; margin: 0 auto; padding: 20px; }", "h1 { color: #333; border-bottom: 2px solid #007bff; padding-bottom: 10px; }", "h2 { color: #555; margin-top: 30px; }", "p { line-height: 1.6; color: #666; }", "</style>", "</head>", "<body>", f"<h1>{title}</h1>" ] for section in sections: heading = section.get("heading", "未命名段落") content = section.get("content", "（无内容）") html_parts.append(f"<h2>{heading}</h2>") html_parts.append(f"<p>{content}</p>") html_parts.append("</body>") html_parts.append("</html>") return "\n".join(html_parts)# 测试运行if __name__ == "__main__": # 创建一个示例 JSON 数据文件 sample_json = { "title": "我的项目帮助文档", "sections": [ {"heading": "快速开始", "content": "请先安装依赖：pip install -r requirements.txt"}, {"heading": "配置说明", "content": "编辑 config.json 文件，设置数据库连接字符串。"}, {"heading": "常见问题", "content": "Q: 如何重启服务？ A: 运行 python app.py --restart"} ] } json_path = "help_data.json" with open(json_path, "w", encoding="utf-8") as f: json.dump(sample_json, f, ensure_ascii=False, indent=2) # 生成 HTML doc_data = load_docs_from_json(json_path) html_content = generate_html(doc_data) # 写入 HTML 文件 with open("help.html", "w", encoding="utf-8") as f: f.write(html_content) print("HTML 帮助页面已生成：help.html") # 可选：在浏览器中自动打开（Windows 下） # import webbrowser # webbrowser.open("help.html")运行结果 ：执行后，你会得到一个 help.html，在浏览器中打开就是一个整洁的帮助页面。这个例子只用了 2 分钟，但已经足够应对大多数小型项目。## 进阶技巧：让文档生成自动化以上两个示例已经能覆盖 80% 的需求。如果你想更进一步，可以：- 结合 Git 钩子 ：在 pre-commit 钩子中自动运行生成脚本，确保文档和代码同步。- 添加搜索功能 ：在 HTML 页面中嵌入 JavaScript 搜索框，让用户快速定位内容。- 支持多语言 ：通过配置文件切换输出语言（Markdown、HTML、JSON 等）。## 总结3 分钟手搓一个帮助文档，听起来像吹牛，但通过这两个实战示例，我们确实做到了：第一个示例从代码注释自动生成 Markdown，适合开发者文档；第二个示例从 JSON 数据生成 HTML，适合用户手册。核心思路是用 Python 标准库 + 少量逻辑 ，快速解决文档痛点。手搓的好处是完全可控------你可以随时修改样式、添加功能，而不需要学习复杂的框架。当然，如果项目规模变大，建议迁移到专业工具，但初期用这种方法，能帮你节省大量时间。下次遇到"写文档"的需求，别再手动敲 Markdown 了，试试自己搓一个生成器吧------3 分钟，真的够用！