设置

LangChain 文档由两个部分组成：

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

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

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

类似于代码检查，我们认识到编写文档可能会让人感到烦恼。如果您不想做这件事，请联系项目维护者，他们会帮助您完成。我们不希望这成为贡献优秀代码的障碍。

📜 主文档​

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

文档是使用ipython笔记本（.ipynb文件）和markdown（.mdx文件）的组合编写的。笔记本被转换为markdown，然后使用Docusaurus 2构建。

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

修改文档后：

1. 运行代码检查和格式化命令（见下文），以确保文档格式良好且无错误。
2. 可选地，在本地构建文档以验证更改看起来是否良好。
3. 提交一个包含更改的拉取请求。
4. 您可以通过点击拉取请求Conversation页面上的View deployment或Visit Preview按钮来预览和验证更改是否符合预期。这将带您进入文档更改的预览页面。

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

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

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

从monorepo根目录，运行以下命令以安装依赖项：

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

构建​

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

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

在构建文档之前，清理构建目录总是一个好主意：

make docs_clean
make api_docs_clean

接下来，您可以按照以下步骤构建文档：

make docs_build
make api_docs_build

make api_docs_quick_preview

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

make docs_linkcheck
make api_docs_linkcheck

代码检查和格式化​

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

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

验证文档更改​

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