跳到主要内容
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. 提交包含更改的 pull request。
  4. 您可以通过单击 pull request Conversation 页面上的 View deployment 或 Visit Preview 按钮来预览和验证更改是否符合您的预期。这将带您进入文档更改的预览。

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

编写完文档后，您可能需要在本地进行代码检查和构建文档，以确保它看起来良好且没有错误。

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

构建​

构建文档的代码位于 monorepo 的 /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

代码检查和格式化​

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

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

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

make format
make lint

验证文档更改​

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

此页是否对您有帮助？