跳到主要内容
Open on GitHub

设置

LangChain 文档由两部分组成

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

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

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

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

📜 主要文档​

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

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

欢迎对主要文档做出贡献！🥰

修改文档后

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

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

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

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

构建​

构建文档的代码位于单体仓库的 /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 参考有用，代码库必须有良好的文档。这意味着所有函数、类和方法都应该有文档字符串（docstring），解释它们的功能、参数以及返回值。这通常是一个好习惯，但对于 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

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

make format
make lint

验证文档更改​

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