设置

LangChain 文档包含两个部分

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

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

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

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

📜 主文档

主文档的内容位于单一仓库的 /docs 目录中。

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

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

修改文档后

1. 运行代码风格检查和格式化命令（见下文），以确保文档格式良好且无错误。
2. 可以选择在本地构建文档以验证更改是否正常。
3. 提交包含更改的拉取请求。
4. 您可以通过单击拉取请求“对话”页面上的“查看部署”或“访问预览”按钮来预览和验证更改是否符合预期。这将带您进入文档更改的预览。

⚒️ 本地代码风格检查和构建文档

编写完文档后，您可能希望在本地对文档进行代码风格检查和构建，以确保其外观良好且无错误。

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

从**单一仓库根目录**运行以下命令以安装依赖项

poetry install --with lint,docs --no-root

构建

构建文档的代码位于单一仓库的 /docs 目录中。

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

在构建文档之前，始终建议清理构建目录

make docs_clean
make api_docs_clean

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

make docs_build
make api_docs_build

提示

make api_docs_build 命令需要很长时间。如果您对 API 文档进行了一些美观上的更改并希望查看其外观，请使用

make api_docs_quick_preview

它只会构建 API 参考的一个小子集。

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

make docs_linkcheck
make api_docs_linkcheck

代码风格检查和格式化

主文档从**单一仓库根目录**进行代码风格检查。要对主文档进行代码风格检查，请从那里运行以下命令

make lint

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

make format

⌨️ 代码内文档

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

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

我们通常遵循 Google Python 风格指南 中的文档字符串规范。

以下是一个记录良好的函数示例

def my_function(arg1: int, arg2: str) -> float:
    """This is a short description of the function. (It should be a single sentence.)

    This is a longer description of the function. It should explain what
    the function does, what the arguments are, and what the return value is.
    It should wrap at 88 characters.

    Examples:
        This is a section for examples of how to use the function.

        .. code-block:: python

            my_function(1, "hello")

    Args:
        arg1: This is a description of arg1. We do not need to specify the type since
            it is already specified in the function signature.
        arg2: This is a description of arg2.

    Returns:
        This is a description of the return value.
    """
    return 3.14

代码风格检查和格式化

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

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

cd [root]/libs/langchain-community

如果您尚未这样做，请为该包设置虚拟环境。

安装该包的依赖项。

poetry install --with lint

然后，您可以运行以下命令对代码内文档进行代码风格检查和格式化

make format
make lint

验证文档更改

将文档更改推送到仓库后，您可以通过单击拉取请求“对话”页面上的“查看部署”或“访问预览”按钮来预览和验证更改是否符合预期。这将带您进入文档更改的预览。此预览由 Vercel 创建。