跳到主要内容

文档贡献指南

本指南帮助您为LangChainGo贡献文档。我们特别需要有关教程和操作指南的帮助！

文档结构​

我们的文档分为四个主要类别：

1. 概念​

目的: 解释理念并提供背景信息

  • 架构概览
  • 设计决策
  • 理论基础

2. 教程​

目的: 分步学习体验

  • 完整的可运行项目
  • 进阶复杂度
  • 实际应用案例

3. 操作指南​

目的: 解决特定问题

  • 针对单一任务
  • 假设读者具备一定知识
  • 实用解决方案

4. API参考文档​

目的: 技术规范

  • 从代码注释生成
  • 完整参数文档
  • 使用示例

编写教程​

教程是完整的学习体验。以下是编写优秀教程的方法：

教程模板​

# 构建[您要构建的内容]

[读者将要构建的一句话描述]

## 您将要构建的项目

一个 [类型的应用程序]，它：
- [功能1]
- [功能2]
- [功能3]

## 先决条件

- Go 1.21+
- [所需API密钥]
- [其他要求]

## 步骤1：[第一个任务]

[简要说明此步骤的目的]

```go
// 完整的可运行代码

步骤2：[下一个任务]​

[继续进行逐步操作...]

运行应用程序​

# 清晰的操作命令

下一步​

  • [潜在改进]
  • [相关教程]

### 教程指南

1. **从简单开始**: 用最少的代码开始
2. **逐步增加复杂度**: 每步添加一点复杂性
3. **解释原因**: 不仅展示怎么做，还要说明为什么
4. **完整代码**: 每个代码块都应可运行
5. **测试一切**: 确保所有示例代码有效

## 编写操作指南

操作指南解决特定问题。它们与教程不同：

### 操作指南模板

```markdown
# 如何[具体任务]

## 问题

[清晰描述要解决问题的说明]

## 解决方案

[简要概述方法]

## 实现

```go
// 集中代码示例

考虑事项​

  • [性能影响]
  • [安全考虑]
  • [替代方法]

相关指南​

  • [相关操作指南链接]

### 操作指南指南

1. **解决一个问题**: 专注于解决一个具体问题
2. **清晰标题**: 使用 "如何X" 格式
3. **最小化设置**: 不重复基本设置
4. **展示替代方案**: 当合适时，显示其他方法
5. **实用重点**: 真实的开发人员面临的问题

## 文档风格指南

### 语言和语气

- **直接明了**: 避免华丽的语言
- **主动语态**: "配置客户端" 而不是 "应配置客户端"
- **现在时态**: "此函数返回" 而不是 "此函数将返回"
- **您/您的**: 直接面向读者

### 代码示例

```go
// DO: 完整的可运行示例
package main

import (
    "context"
    "fmt"
    "log"

    "github.com/tmc/langchaingo/llms/openai"
)

func main() {
    llm, err := openai.New()
    if err != nil {
        log.Fatal(err)
    }
    // ...其余示例代码
}
// DON'T: 不完整的片段
llm := openai.New() // 缺少错误处理
// ...这里发生魔法...

格式约定​

  • 标题: 使用句子形式，而不是标题形式
  • 代码块: 始终指定语言 ( ```go)
  • 强调: 用粗体表示重要概念
  • 列表: 使用 - 表示无序列表
  • 链接: 使用描述性文本，不要使用 "点击这里"

避免事项​

  • 文档中不使用表情符号
  • 不使用营销语言或炒作
  • 不提供不完整的示例
  • 不硬编码API密钥
  • 不依赖外部服务

贡献缺失文档​

我们有许多教程和指南标记为 "即将推出"。以下是贡献方法：

1. 选择主题​

  • 查看我们的 教程 和 操作指南，寻找标记为“即将推出”的主题。
  • 审查开放问题，避免重复工作。

2. 打开一个问题​

在编写之前，请打开一个问题以：

  • 声明主题（避免重复工作）
  • 讨论方法
  • 获取大纲反馈

3. 编写内容​

遵循上述模板和指南。

4. 测试一切​

  • 确保所有代码示例可运行
  • 在干净的环境中测试
  • 验证API密钥处理正确

5. 提交PR​

创建一个拉取请求，包括：

  • 清晰标题：docs: 添加教程 [主题]
  • 跟踪问题链接
  • 概述涵盖的内容

本地开发​

构建文档​

本地开发​

cd docs
npm install
npm run start

这将在 http://localhost:3000 启动一个本地服务器。

Docker 开发​

对于容器化环境：

cd docs

# 快速开发服务器，带实时重载
make docker-dev

# 或构建并运行持久容器
make docker-run

# 完成后清理
make docker-clean

Docker 方法确保了 Node.js 环境和依赖项的一致性。

测试文档​

提交前：

  1. 检查链接：确保所有链接都能正常工作。
  2. 运行代码：测试所有的代码示例。
  3. 审查格式：在浏览器中查看渲染效果。
  4. 运行 Vale 检查：使用 Vale 检查风格一致性。
  5. 拼写检查：使用编辑器的拼写检查功能。

运行 Vale 检查​

Vale 自动检查文档的风格和一致性：

# 安装 Vale（在 macOS 上）
make lint-deps

# 检查所有文档
make lint-docs

# 或直接运行 Vale
vale docs

Vale 检查的内容包括：

  • 标题使用句首大写
  • 术语一致性
  • 技术术语的拼写
  • 写作风格指南

文档示例​

好的教学文档示例​

好的操作指南示例​

需要帮助？​

  • 查看现有文档中的风格示例
  • 在 GitHub 讨论区 中提问
  • 为你的 PR 打上 documentation 标签以加快审查速度

贡献者感谢​

文档贡献者将在以下地方获得认可：

  • 文档本身（作者署名）
  • 发布说明
  • 贡献者名单

感谢你帮助改进 LangChainGo 文档！