通常情况下,除非有迫切需求,我们不会合并来自外部贡献者的新教程。
快速入门
快速编辑:修复拼写错误
对于简单的修改(如修正拼写错误),您无需配置本地开发环境,可直接在 GitHub 上编辑:前提条件:
- 拥有 GitHub 账户
- 熟悉 GitHub Web 界面提交 Pull Request 的基本操作
1
找到页面
导航至任意文档页,点击页面底部的“建议编辑”链接
2
Fork 仓库
GitHub 将提示您将仓库 Fork 到您的账户。请务必 Fork 至您的!
3
进行修改
在 GitHub 的网页编辑器中直接修正拼写错误
4
提交更改
点击
Commit changes...,并为提交起一个描述性标题,例如 fix(docs): 描述5
创建 Pull Request
GitHub 将引导您创建 Pull Request。标题格式如
docs: 修正 X 中的拼写错误,并遵循 PR 模板中的检查清单文档类 PR 通常会在几天内完成审核。请关注您的 PR,及时响应维护者的反馈。
完整开发 IDE 配置
对于较大规模的修改或持续贡献,请设置本地开发环境。我们的文档使用 Mintlify 构建,支持本地预览和实时重载。2
了解 Mintlify
查阅 Mintlify 文档,了解组件用法和最佳实践——您也可以参考现有文档作为示例
3
构建系统与开发环境
按照以下步骤设置您的开发环境
- VSCode
- 其他 IDE
打开项目时,
.vscode/settings.json 中的设置会自动应用,无需额外配置。推荐扩展:在 VSCode 中打开“Extensions”标签页时,可能会提示您自动安装这些扩展。构建系统
我们的文档采用构建流水线,允许使用 MDX 编写并使用 Mintlify 组件。源文件位于src/,构建输出位于 build/。您可以运行带热重载的本地开发服务器,在浏览器中即时查看更改效果。
2
启动开发服务器
3
进行修改
编辑
src/ 中的文件,并在浏览器中立即看到更改效果文档类型
在适用的情况下,所有文档必须同时提供 Python 和 JavaScript/TypeScript 版本。详情请参阅本地化指南。
概念指南
概念指南从抽象层面介绍核心概念,提供深入理解。特点
特点
- 注重理解:解释事物为何如此运作
- 宏观视角:比其他类型更宽广、更高层次的视野
- 面向设计:阐释决策与权衡取舍
- 丰富语境:使用类比与对比
技巧
技巧
- 解释设计决策 —— 为什么存在概念 X?
- 使用类比并引用替代方案
- 避免混入过多参考内容
- 链接到相关教程和操作指南
- 聚焦于 “为什么”,而非“怎么做”
参考文档
参考文档包含详细、底层的信息,精确描述现有功能及其使用方法。参考文档特点
参考文档特点
- 信息导向:描述存在的内容
- 全面覆盖:涵盖所有参数和选项
- 结构清晰:系统化组织
- 权威准确:技术细节的权威来源
LangChain 参考文档类型
LangChain 参考文档类型
- API 参考:从代码文档字符串自动生成
- 集成指南:特定提供商/工具的手动文档
- 配置参考:详细的参数规范
- 模式文档:数据结构和格式规范
如何贡献参考文档
如何贡献参考文档
- API 参考:更新源码仓库中的文档字符串
- 集成指南:在文档仓库的
/src/目录下创建/编辑.mdx文件 - 手动参考:编辑现有页面
LangChain 参考文档最佳实践
LangChain 参考文档最佳实践
- 集成一致性:遵循现有模式编写特定提供商的文档
- 代码示例:包含基础用法及常见边缘情况/失败模式
- 版本兼容性:注明功能所需的特定版本
- LangChain Python API 参考(从文档字符串自动生成)
- LangChain JavaScript/TypeScript API 参考(从文档字符串自动生成)
- 新增集成或提供商需专属参考页面
- 复杂配置选项需详细说明
- API 变更引入新参数或行为
- 社区频繁询问特定功能
写作标准
Mintlify 组件
使用适当的 Mintlify 组件 提升可读性:- 提示框
- 结构
- 代码
<Note>用于补充信息<Warning>用于重要警告和破坏性变更<Tip>用于最佳实践和建议<Info>用于中立的背景信息<Check>用于成功确认
页面结构
每个文档页面必须以 YAML frontmatter 开头:本地化
在可能的情况下,所有文档必须同时本地化为 Python 和 JavaScript/TypeScript 版本。为此,我们使用自定义内联语法区分应出现在一种或两种语言中的部分:我们不希望因语言版本不对称而阻碍贡献。如果某项功能仅在一个语言中可用,则可以仅在该语言中提供文档,直到另一语言跟上为止。在这种情况下,请注明该功能尚未在另一语言中提供。
如果您需要帮助在 Python 和 JavaScript/TypeScript 之间翻译内容,请在社区 Slack 中提问,或在您的 PR 中标记维护者。
质量标准
通用指南
避免重复
避免重复
多个页面覆盖相同内容难以维护且易造成混淆。每个概念或功能应仅有一个权威页面。链接到其他指南,而非重复解释。
频繁链接
频繁链接
文档各部分并非孤立存在。频繁链接到其他部分,以便用户了解不熟悉的话题。这包括链接到 API 参考和概念部分。
简洁明了
简洁明了
采取少即是多的原则。若已有良好解释的其他部分,链接过去即可,除非您的内容提供了新视角。
可访问性要求
确保文档对所有用户均可访问:- 使用标题和列表结构化内容,便于快速浏览
- 使用具体、可操作的链接文本,而非“点击这里”
- 为所有图片和图表提供描述性 alt 文本
测试与验证
提交文档前:1
测试所有代码
运行所有代码示例,确保其正确无误
2
检查格式
3
本地构建
4
检查链接
确保所有内部链接正常工作
代码内文档
语言与风格
对所有公共函数使用Google 风格文档字符串并完整标注类型提示。
- 语气:使用第二人称(“您”)进行指导
- 时态:使用主动语态和现在时
- 清晰度:为技术受众编写清晰、直接的语言
- 一致性:全文使用一致的术语
- 简洁性:句子简洁,同时提供必要上下文
代码示例
代码示例要求:1
完整性
包含完整、可运行的示例,用户可直接复制执行且无错误
2
真实性
使用真实数据,而非“foo”或“example”等占位符
3
错误处理
展示正确的错误处理和边缘情况管理
4
注释说明
为复杂逻辑添加解释性注释
获取帮助
我们的目标是尽可能简化开发者配置。如在配置过程中遇到任何困难,请在社区 Slack 中提问,或发布论坛帖子。您现在已具备为 LangChain 贡献高质量文档所需的一切!