Skip to main content

设置

LangChain 文档由两个部分组成:

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

“API 参考”主要由 sphinx 自动生成。 基于代码,并由 Read the Docs 托管。

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

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

📜 主文档

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

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

欢迎随时为主文档做贡献!🥰

修改文档后:

  1. 运行 linting 和格式化命令(见下文),确保文档格式良好且没有错误。
  2. 可选地在本地构建文档,以验证更改是否看起来不错。
  3. 提交包含更改的拉取请求。
  4. 你可以通过点击拉取请求 Conversation 页面上的 查看部署访问预览 按钮来预览和验证更改是否符合你的期望。这将带你查看文档更改的预览。

⚒️ 本地 linting 和构建文档

在撰写文档后,你可能想要进行 linting 和构建文档 在本地确保它看起来不错且没有错误。

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

monorepo 根目录,运行以下命令以安装依赖项:

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

Building

The code that builds the documentation is located in the /docs directory of the monorepo.

In the following commands, the prefix api_ indicates that those are operations for the API Reference.

Before building the documentation, it is always a good idea to clean the build directory:

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

代码检查和格式化

主文档从 单一代码库根目录 进行代码检查。要检查主文档,请从那里运行以下命令:

make lint

如果您有与格式相关的错误,可以通过以下方式自动修复:

make format

⌨️ 代码内文档

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

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

我们通常遵循 Google Python Style Guide 来编写文档字符串。

以下是一个文档良好的函数示例:


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 社区 包,您将更改 工作目录指向 LangChain 社区 目录:

cd [root]/libs/langchain-community

如果尚未设置,请为该包设置一个虚拟环境。

安装该包的依赖项。

poetry install --with lint

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

make format
make lint

验证文档更改

在将文档更改推送到仓库后,您可以预览并验证更改是否符合您的期望, 通过点击拉取请求 对话 页面上的 查看部署访问预览 按钮。 这将带您查看文档更改的预览。 此预览由 Vercel 创建。


Was this page helpful?


You can also leave detailed feedback on GitHub.

扫我,入群扫我,找书