Skip to main content
Open on GitHub

设置

LangChain 文档包含两个组成部分：

  1. 主要文档：托管于 python.langchain.com， 此综合资源是面向用户的主要文档。 它涵盖了教程、用例、集成等广泛主题，为使用 LangChain 进行构建提供了广泛的指导。 此文档的内容位于 monorepo 的 /docs 目录中。
  2. 代码内文档：这是代码库自身的文档，也用于生成面向外部的 API 参考。 API 参考的内容是通过扫描代码库中的文档字符串自动生成的。因此，我们要求 开发人员好好记录他们的代码。

API 参考 主要由 sphinx 从代码中自动生成，并由 Read the Docs 托管。

我们感谢对文档的所有贡献，无论是修复拼写错误、 添加新教程或示例，无论是在主要文档中还是在 API 参考中。

与代码检查类似，我们认识到编写文档可能很烦人。如果您不想 写文档，请联系项目维护者，他们可以帮助您。我们不希望这成为贡献优质代码的障碍。

📜 主要文档​

主要文档的内容位于 monorepo 的 /docs 目录中。

文档使用 ipython notebook (.ipynb 文件) 和 markdown (.mdx 文件) 的组合编写。Notebook 会被转换为 markdown ，然后使用 Docusaurus 2 进行构建。

欢迎随时为主要文档做出贡献！🥰

修改文档后：

  1. 运行代码检查和格式化命令（如下所示），以确保文档格式良好且无错误。
  2. 可选地在本地构建文档，以验证更改的外观。
  3. 通过在拉取请求的 Conversation 页面上点击 View deployment 或 Visit Preview 按钮来提交更改。这将带您到文档更改的预览页面。

⚒️ 在本地检查和构建文档​

编写完文档后，您可能希望在本地检查和构建文档 ，以确保其外观良好且没有错误。

如果您无法在本地构建，那也没关系，因为您可以在拉取请求页面上 看到文档的预览。

构建​

构建文档的代码位于 monorepo 的 /docs 目录中。

在以下命令中，前缀 api_ 表明这些是针对 API 参考的操作。

在构建文档之前，最好先清理构建目录：

make docs_clean
make api_docs_clean

接下来，您可以按照以下说明构建文档：

make docs_build
make api_docs_build
tip

make api_docs_build 命令耗时较长。如果您对 API 文档进行的是外观上的更改，并希望查看其效果，请使用：

make api_docs_quick_preview

它只会构建 API 参考的一小部分。

最后，运行链接检查器以确保所有链接都有效：

make docs_linkcheck
make api_docs_linkcheck

检查和格式化​

主要文档是从 monorepo 根目录 进行代码检查的。要检查主要文档，请从那里运行以下命令：

make lint

如果您遇到与格式相关的错误，可以使用以下命令自动修复：

make format

⌨️ 代码内文档​

代码内文档主要由 sphinx 从代码中自动生成，并由 Read the Docs 托管。

为了使 API 参考有用，代码库必须有良好的文档。这意味着所有函数、类和方法都应该有一个文档字符串，解释它们的作用、参数以及返回值。这通常是好的做法，但对于 LangChain 尤其重要，因为 API 参考是开发人员理解如何使用代码库的主要资源。

我们通常遵循 Google Python 风格指南 来编写文档字符串。

这是一个文档良好的函数的示例：


def my_function(arg1: int, arg2: str) -> float:
    """对函数进行简短描述。（应为一句）。

    这是对函数更长的描述。它应解释
    函数的作用、参数和返回值。
    它应该在 88 个字符处换行。

    示例：
        这是函数使用示例的部分。

        .. code-block:: python

            my_function(1, "hello")

    Args:
        arg1: arg1 的描述。无需指定类型，因为
            它已在函数签名中指定。
        arg2: arg2 的描述。

    Returns:
        返回值的描述。
    """
    return 3.14

检查和格式化​

代码内文档是从属于被记录包的目录进行检查的。

例如，如果您正在处理 langchain-community 包，您需要更改 工作目录到 langchain-community 目录：

cd [root]/libs/langchain-community

然后您可以运行以下命令来检查和格式化代码内文档：

make format
make lint

验证文档更改​

在将文档更改推送到仓库后，您可以通过在拉取请求 Conversation 页面上点击 View deployment 或 Visit Preview 按钮来预览和验证更改是否符合您的预期。这将带您到文档更改的预览页面。 此预览由 Vercel 创建。