我们通常不会在没有紧急需求的情况下合并来自外部贡献者的新教程。如果您认为文档中缺少某个特定主题或未充分涵盖,请提出新问题。
入门
快速编辑:修复拼写错误
对于修复拼写错误等简单更改,您可以直接在 GitHub 上编辑,而无需设置本地开发环境1
查找页面
导航到任何文档页面,滚动到页面底部,然后单击链接“在 GitHub 上编辑此页面的源代码”
2
分叉仓库
GitHub 将提示您将存储库分叉到您的帐户。请务必分叉到您的
3
进行更改
直接在 GitHub 的网页编辑器中更正拼写错误
4
提交您的更改
单击
Commit changes...并为您的提交提供一个描述性标题,例如fix(docs): 更改摘要。如果适用,添加扩展描述5
创建拉取请求
GitHub 会将您重定向到创建拉取请求。给它一个标题(通常与提交相同),并按照 PR 模板清单(如果存在)进行操作
文档 PR 通常会在几天内审查。请关注您的 PR,以解决维护者提出的任何反馈。除非您有新的信息提供,否则请勿催促 PR - 维护者将在有空时处理。
完整的开发 IDE 设置
对于较大的更改或持续贡献,在您的机器上设置本地开发环境非常重要。我们的文档构建管道提供本地预览和实时重新加载,这对于确保您的更改在提交前按预期显示至关重要。请查看文档仓库README.md 中概述的设置环境的步骤。文档类型
在适用的情况下,所有文档都必须有 Python 和 JavaScript/TypeScript 两种翻译。有关详细信息,请参阅我们的本地化指南。
概念指南
概念指南抽象地涵盖核心概念,提供深刻的理解。特点
特点
- 以理解为中心:解释事物为何如此运作
- 广阔的视角:比其他类型更高更广的视角
- 以设计为导向:解释决策和权衡
- 内容丰富:使用类比和比较
提示
提示
- 解释设计决策 - “为什么概念 X 存在?”
- 使用类比和参考替代方案
- 避免混入过多的参考内容
- 链接到相关的教程和操作指南
- 专注于“为什么”而不是“如何”
参考资料
参考文档包含详细的低级信息,确切描述了存在哪些功能以及如何使用它们。JavaScript/TypeScript 参考
- 描述存在什么(所有参数、选项、返回值)
- 全面且结构清晰,便于查找
- 作为技术细节的权威来源
贡献参考资料
贡献参考资料
请参阅JavaScript/TypeScript 参考文档的贡献指南。
LangChain 参考最佳实践
LangChain 参考最佳实践
- 保持一致;遵循现有特定于提供商的文档模式
- 包括基本用法(代码片段)和常见的边缘情况/故障模式
- 注意功能何时需要特定版本
何时创建新的参考文档
何时创建新的参考文档
- 新的集成或提供商需要专门的参考页面
- 复杂的配置选项需要详细说明
- 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 风格文档字符串。
- 语态:指令使用第二人称(“您”)
- 时态:使用主动语态和现在时
- 清晰度:为技术受众撰写清晰、直接的语言
- 一致性:始终使用一致的术语
- 简洁性:保持句子简洁,同时提供必要的上下文
代码示例
发布前务必测试代码示例。切勿包含真实的 API 密钥或机密。
1
完整性
包括完整的、可运行的示例,用户可以复制并执行而不会出错
2
真实性
使用真实数据而不是“foo”或“example”之类的占位符值
3
错误处理
展示适当的错误处理和边缘情况管理
4
文档
为复杂逻辑添加解释性注释
获取帮助
我们的目标是尽可能简化开发者设置。如果您在设置时遇到任何困难,请在社区 Slack 中提问或在论坛上发帖。现在您已经拥有向 LangChain 贡献高质量文档所需的一切!🎤🦜
以编程方式连接这些文档到 Claude、VSCode 等,通过 MCP 获取实时答案。