我们通常不接受外部贡献者提交的新教程,除非有特殊需要。如果您觉得文档中缺少某个主题或涵盖不足,请提出新问题。
入门
快速编辑:修复拼写错误
对于简单的更改,例如修复拼写错误,您可以直接在 GitHub 上编辑,而无需设置本地开发环境先决条件
- 一个 GitHub 帐户
- 对贡献的fork-and-pull 工作流程有基本了解
1
查找页面
导航到任何文档页面,滚动到页面底部,然后单击“在 GitHub 上编辑此页面的源代码”链接
2
分叉仓库
GitHub 将提示您将存储库 fork 到您的帐户。请确保 fork 到您的
3
进行更改
直接在 GitHub 的网页编辑器中更正拼写错误
4
提交您的更改
单击
Commit changes... 并为您的提交提供一个描述性标题,例如 fix(docs): summary of change。如果适用,添加扩展描述5
创建拉取请求
GitHub 将重定向您创建拉取请求。给它一个标题(通常与提交相同),并遵循 PR 模板清单(如果存在)
文档 PR 通常会在几天内进行审核。请关注您的 PR,以处理维护者提供的任何反馈。除非您有新的信息需要提供,否则不要催促 PR - 维护者会根据他们的可用性进行处理。
完整的开发 IDE 设置
对于较大的更改或持续的贡献,在您的机器上设置本地开发环境非常重要。我们的文档构建管道提供本地预览和实时重新加载功能,您可以在编辑时使用,这对于确保您的更改在提交前按预期显示非常重要。 请查阅文档仓库README.md 中概述的环境设置步骤。文档类型
在适用情况下,所有文档都必须有 Python 和 JavaScript/TypeScript 两种语言的翻译。有关详细信息,请参阅我们的本地化指南。
概念指南
概念指南抽象地涵盖核心概念,提供深刻的理解。特点
特点
- 以理解为中心:解释事物运作的原因
- 广阔视角:比其他类型更高更广的视角
- 面向设计:解释决策和权衡
- 内容丰富:使用类比和比较
提示
提示
- 解释设计决策 - “概念 X 为何存在?”
- 使用类比并引用替代方案
- 避免混入过多的参考内容
- 链接到相关教程和操作指南
- 侧重于 “为什么” 而不是“怎么做”
参考资料
参考文档包含详细的、低级的信息,准确描述了存在哪些功能以及如何使用它们。Python 参考
- 描述存在的内容(所有参数、选项、返回值)
- 全面且结构化,便于查找
- 作为技术细节的权威来源
贡献参考资料
贡献参考资料
请参阅Python 参考文档的贡献指南。
LangChain 参考最佳实践
LangChain 参考最佳实践
- 保持一致;遵循现有提供商特定文档的模式
- 包括基本用法(代码片段)和常见的边缘情况/故障模式
- 注意功能何时需要特定版本
何时创建新的参考文档
何时创建新的参考文档
- 新的集成或提供商需要专门的参考页面
- 复杂的配置选项需要详细解释
- API 更改引入了新的参数或行为
- 社区经常询问有关特定功能的问题
写作标准
参考文档有不同的标准——有关详细信息,请参阅参考文档贡献指南。
Mintlify 组件
使用适当的 Mintlify 组件来增强可读性- 标注
- 结构
- 代码
<Note>用于有用的补充信息<Warning>用于重要的注意事项和重大更改<Tip>用于最佳实践和建议<Info>用于中立的上下文信息<Check>用于成功确认
页面结构
每个文档页面都必须以 YAML frontmatter 开头本地化
所有文档在可能的情况下都必须本地化为 Python 和 JavaScript/TypeScript。为此,我们使用自定义的内联语法来区分应该出现在一种或两种语言中的部分我们不希望缺乏对等性阻碍贡献。如果某个功能仅在一种语言中可用,那么只使用该语言的文档是可以的,直到另一种语言赶上。在这种情况下,请包含一个说明该功能在其他语言中尚未可用的注释。
如果您在 Python 和 JavaScript/TypeScript 之间翻译内容时需要帮助,请在社区 Slack 中提问或在您的 PR 中标记维护者。
质量标准
一般准则
避免重复
避免重复
多页覆盖相同内容难以维护并造成混淆。每个概念或功能应该只有一个规范页面。链接到其他指南而不是重新解释。
频繁链接
频繁链接
文档部分并非独立存在。频繁链接到其他部分,以便用户了解不熟悉的主题。这包括链接到 API 参考和概念部分。
保持简洁
保持简洁
采取少即是多的方法。如果存在带有良好解释的另一部分,请链接到它而不是重新解释,除非您的内容提供了一个新的角度。
无障碍要求
确保所有用户都能访问文档- 使用标题和列表构建内容,便于快速浏览
- 使用具体、可操作的链接文本,而不是“点击这里”
- 为所有图像和图表添加描述性替代文本
测试和验证
提交文档之前1
测试所有代码
运行所有代码示例以确保它们正常工作
2
检查格式
3
本地构建
4
查看链接
检查所有内部链接是否正常工作
代码内文档
语言和风格
对所有公共函数使用带有完整类型提示的Google 风格文档字符串。
- 语气:说明使用第二人称(“你”)
- 时态:使用主动语态和现在时
- 清晰度:为技术受众撰写清晰、直接的语言
- 一致性:在整个文档中使用一致的术语
- 简洁性:在提供必要上下文的同时保持句子简洁
代码示例
发布前务必测试代码示例。切勿包含真实的 API 密钥或机密。
1
完整性
包含完整、可运行的示例,用户可以复制并执行而不会出错
2
真实性
使用真实数据,而不是“foo”或“example”等占位符值
3
错误处理
展示正确的错误处理和边缘情况管理
4
文档
为复杂的逻辑添加解释性注释
获取帮助
我们的目标是实现尽可能简单的开发者设置。如果您在设置过程中遇到任何困难,请在社区 Slack 中提问或发布论坛帖子。现在您已经掌握了向 LangChain 贡献高质量文档所需的一切!🎤🦜
以编程方式连接这些文档到 Claude、VSCode 等,通过 MCP 获取实时答案。