设置
LangChain 文档由两个部分组成:
- 主要文档:托管在 python.langchain.com,
这个综合资源作为主要的用户文档。
它涵盖了广泛的主题,包括教程、用例、集成,
以及更多,提供了关于使用 LangChain 构建的广泛指导。
该文档的内容位于单一代码库的
/docs
目录中。 - 代码内文档:这是对代码库本身的文档, 也用于生成外部的 API 参考。 API 参考的内容是通过扫描代码库中的文档字符串自动生成的。因此,我们要求 开发者应当很好地记录他们的代码。
“API 参考”主要由 sphinx 自动生成。 基于代码,并由 Read the Docs 托管。
我们感谢所有对文档的贡献,无论是修复一个错别字, 添加一个新的教程或示例,无论是在主文档还是 API 参考中。
与代码检查类似,我们认识到文档编写可能会令人烦恼。如果您不想 这样做,请联系项目维护者,他们可以帮助您。我们不希望这成为良好代码贡献的障碍。
📜 主文档
主文档的内容位于单一代码库的 /docs
目录中。
文档是使用 ipython 笔记本(.ipynb
文件)结合编写的。
和 markdown (.mdx
文件)。笔记本被转换为 markdown
然后使用 Docusaurus 2 构建。
欢迎随时为主文档做贡献!🥰
修改文档后:
- 运行 linting 和格式化命令(见下文),确保文档格式良好且没有错误。
- 可选地在本地构建文档,以验证更改是否看起来不错。
- 提交包含更改的拉取请求。
- 你可以通过点击拉取请求
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
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 创建。