跳到内容

开发 - 贡献

首先，你可能需要了解 帮助 FastAPI 并获得帮助 的基本方式。

开发中

如果你已经克隆了 FastAPI 仓库 并想深入代码，这里有一些设置环境的指南。

虚拟环境

按照说明为 fastapi 的内部代码创建并激活 虚拟环境。

使用 pip 安装依赖

激活环境后，安装所需软件包

$ pip install -r requirements.txt

---> 100%

它将在你的本地环境中安装所有依赖项和你的本地 FastAPI。

使用本地 FastAPI

如果你创建一个导入并使用 FastAPI 的 Python 文件，并使用本地环境中的 Python 运行它，它将使用你克隆的本地 FastAPI 源代码。

如果你在再次运行该 Python 文件时更新本地 FastAPI 源代码，它将使用你刚刚编辑过的 FastAPI 的最新版本。

这样，你就不必“安装”你的本地版本就能测试每一次更改。

技术细节

这种情况只在你使用此随附的 requirements.txt 进行安装，而不是直接运行 pip install fastapi 时发生。

这是因为在 requirements.txt 文件中，FastAPI 的本地版本被标记为以“可编辑”模式安装，带有 -e 选项。

格式化代码

有一个脚本可以运行来格式化和清理你的所有代码

$ bash scripts/format.sh

它还会自动排序你所有的导入。

测试

有一个脚本可以在本地运行，用于测试所有代码并生成 HTML 格式的覆盖率报告

$ bash scripts/test-cov-html.sh

此命令会生成一个 ./htmlcov/ 目录，如果你在浏览器中打开 ./htmlcov/index.html 文件，你可以交互式地探索代码中被测试覆盖的区域，并留意是否有任何区域缺失。

文档

首先，请确保你已按照上述说明设置好环境，这将安装所有依赖项。

文档实时预览

在本地开发期间，有一个脚本可以构建站点并检查任何更改，实现实时重载

$ python ./scripts/docs.py live

<span style="color: green;">[INFO]</span> Serving on http://127.0.0.1:8008
<span style="color: green;">[INFO]</span> Start watching changes
<span style="color: green;">[INFO]</span> Start detecting changes

它将在 http://127.0.0.1:8008 上提供文档服务。

这样，你就可以编辑文档/源文件并实时查看更改。

提示

或者，你可以手动执行脚本所做相同步骤。

进入语言目录，英文主文档位于 docs/en/

$ cd docs/en/

然后在该目录中运行 mkdocs

$ mkdocs serve --dev-addr 127.0.0.1:8008

Typer CLI (可选)

这里的说明展示了如何直接使用 python 程序运行 ./scripts/docs.py 脚本。

但你也可以使用 Typer CLI，安装补全功能后，你将在终端中获得命令的自动补全。

如果你安装了 Typer CLI，你可以通过以下方式安装补全功能

$ typer --install-completion

zsh completion installed in /home/user/.bashrc.
Completion will take effect once you restart the terminal.

文档结构

文档使用 MkDocs。

并且在 ./scripts/docs.py 中有一些额外的工具/脚本来处理翻译。

提示

你不需要查看 ./scripts/docs.py 中的代码，只需在命令行中使用它。

所有文档都以 Markdown 格式存储在 ./docs/en/ 目录中。

许多教程都包含代码块。

在大多数情况下，这些代码块是实际的完整应用程序，可以直接运行。

事实上，这些代码块并非直接写在 Markdown 中，它们是 ./docs_src/ 目录下的 Python 文件。

在生成站点时，这些 Python 文件会被包含/注入到文档中。

用于测试的文档

大多数测试实际上都针对文档中的示例源文件运行。

这有助于确保

  • 文档是最新的。
  • 文档示例可以直接运行。
  • 大多数功能都通过文档涵盖，并通过测试覆盖率得到保证。

应用与文档同时运行

如果你运行示例，例如

$ fastapi dev tutorial001.py

<span style="color: green;">INFO</span>:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

因为 Uvicorn 默认会使用 8000 端口，所以 8008 端口上的文档不会冲突。

翻译

非常感谢您在翻译方面的帮助！没有社区的帮助，这项工作无法完成。🌎 🚀

以下是帮助翻译的步骤。

提示和指南

  • 检查当前 针对你的语言已有的拉取请求。你可以根据你的语言标签来筛选拉取请求。例如，对于西班牙语，标签是 lang-es。

  • 审查这些拉取请求，提出更改意见或批准它们。对于我不懂的语言，我会等待其他几位审查翻译后才进行合并。

提示

你可以添加带有修改建议的评论到现有的拉取请求中。

查阅关于 添加拉取请求审查 的文档，以批准或请求更改。

  • 查看是否有 GitHub 讨论 来协调你语言的翻译。你可以订阅它，当有新的拉取请求需要审查时，会自动在讨论中添加评论。

  • 如果你翻译页面，请为每个翻译的页面提交一个单独的拉取请求。这将使其他人更容易审查。

  • 要检查你想要翻译的语言的两位字母代码，你可以使用 ISO 639-1 代码列表 表格。

现有语言

假设你想为一个已经有部分页面翻译的语言（如西班牙语）翻译一个页面。

以西班牙语为例，其两位字母代码是 es。因此，西班牙语翻译的目录位于 docs/。

提示

主要（“官方”）语言是英语，位于 docs/en/。

现在运行西班牙语文档的实时服务器

// Use the command "live" and pass the language code as a CLI argument
$ python ./scripts/docs.py live es

<span style="color: green;">[INFO]</span> Serving on http://127.0.0.1:8008
<span style="color: green;">[INFO]</span> Start watching changes
<span style="color: green;">[INFO]</span> Start detecting changes

提示

或者，你可以手动执行脚本所做相同步骤。

进入语言目录，西班牙语翻译位于 docs/

$ cd docs/

然后在该目录中运行 mkdocs

$ mkdocs serve --dev-addr 127.0.0.1:8008

现在你可以访问 http://127.0.0.1:8008 并实时查看你的更改。

你会看到每种语言都包含所有页面。但有些页面尚未翻译，并在顶部有一个信息框，提示缺少翻译。

现在假设你想为 特性 部分添加翻译。

  • 复制文件位于
docs/en/docs/features.md
  • 将其粘贴到完全相同的位置，但针对你想要翻译的语言，例如
docs/docs/features.md

提示

请注意，路径和文件名中唯一的更改是语言代码，从 en 变为 es。

如果你打开浏览器，你会发现现在文档显示了你的新部分（顶部的信息框已消失）。🎉

现在你可以翻译所有内容，并在保存文件时查看其效果。

请勿翻译这些页面

🚨 请勿翻译

  • reference/ 下的文件
  • release-notes.md
  • fastapi-people.md
  • external-links.md
  • newsletter.md
  • management-tasks.md
  • management.md
  • contributing.md

其中一些文件更新非常频繁，翻译会一直滞后，或者它们包含来自英文源文件的主要内容等。

新语言

假设你想为一个尚未有任何页面翻译的语言添加翻译。

假设你想为克里奥尔语添加翻译，而文档中尚未有此语言。

查看上面的链接，”克里奥尔语“的代码是 ht。

下一步是运行脚本以生成一个新的翻译目录

// Use the command new-lang, pass the language code as a CLI argument
$ python ./scripts/docs.py new-lang ht

Successfully initialized: docs/ht

现在你可以在代码编辑器中查看新创建的 docs/ht/ 目录。

该命令创建了一个 docs/ht/mkdocs.yml 文件，其中包含一个简单的配置，继承了 en 版本的所有内容

INHERIT: ../en/mkdocs.yml

提示

你也可以手动创建该文件并填充这些内容。

该命令还为主页创建了一个虚拟文件 docs/ht/index.md，你可以从翻译该文件开始。

你可以按照前面“现有语言”的说明继续该过程。

你可以用这两个文件 docs/ht/mkdocs.yml 和 docs/ht/index.md 提交第一个拉取请求。🎉

预览结果

如上所述，你可以使用 ./scripts/docs.py 配合 live 命令来预览结果（或使用 mkdocs serve）。

完成后，你还可以测试它在线时的样子，包括所有其他语言。

要做到这一点，首先构建所有文档

// Use the command "build-all", this will take a bit
$ python ./scripts/docs.py build-all

Building docs for: en
Building docs for: es
Successfully built docs for: es

这会为每种语言构建所有独立的 MkDocs 站点，将它们组合起来，并在 ./site/ 生成最终输出。

然后你可以使用 serve 命令来提供服务

// Use the command "serve" after running "build-all"
$ python ./scripts/docs.py serve

Warning: this is a very simple server. For development, use mkdocs serve instead.
This is here only to preview a site with translations already built.
Make sure you run the build-all command first.
Serving at: http://127.0.0.1:8008

翻译特有的提示和指南

  • 只翻译 Markdown 文档 (.md)。不要翻译 ./docs_src 中的代码示例。

  • 在 Markdown 文档的代码块中，翻译注释 (# 一个注释)，但其余部分保持不变。

  • 不要更改任何被“``”包围的内容（行内代码）。

  • 以 /// 开头的行，只翻译 | 后的文本部分。其余保持不变。

  • 你可以翻译像 /// warning 这样的信息框，例如翻译成 /// warning | Achtung。但不要更改 /// 后的单词，它决定了信息框的颜色。

  • 不要更改图片、代码文件、Markdown 文档链接中的路径。

  • 然而，当 Markdown 文档被翻译时，链接到其标题的 #hash-parts 可能会改变。如果可能，请更新这些链接。

    • 在翻译后的文档中使用正则表达式 #[^# ] 搜索此类链接。
    • 在你已翻译成你的语言的所有文档中搜索 your-translated-document.md。例如，VS Code 有一个选项“编辑”->“在文件中查找”。
    • 翻译文档时，不要“预先翻译”链接到未翻译文档中标题的 #hash-parts。