开发 - 贡献¶

首先，您可能想了解帮助 FastAPI 和获得帮助的基本方法帮助 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 8008

Typer CLI（可选）¶

此处的说明向您展示如何使用 ./scripts/docs.py 中的脚本以及 python 程序直接进行操作。

但您也可以使用 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 讨论来协调您语言的翻译。您可以订阅它，当有新的拉取请求要审查时，会向讨论添加一条自动评论。
如果您翻译页面，请为每页翻译添加一个拉取请求。这将使其他人更容易审查它。
要检查您要翻译的语言的 2 字母代码，您可以使用表格 ISO 639-1 代码列表。

现有语言¶

假设您想为已经有一些页面翻译的语言（例如西班牙语）翻译一个页面。

对于西班牙语，2 字母代码是 es。因此，西班牙语翻译的目录位于 docs/es/。

提示

主要（“官方”）语言是英语，位于 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/es/

$ cd docs/es/

然后在该目录中运行 mkdocs

$ mkdocs serve --dev-addr 8008

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

您会看到每种语言都有所有页面。但有些页面没有翻译，并且在顶部有一个信息框，提示缺少翻译。

现在假设您想为功能部分添加翻译。

复制位于

docs/en/docs/features.md

将其粘贴到完全相同的位置，但对于您要翻译的语言，例如

docs/es/docs/features.md

提示

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

如果您访问浏览器，您会看到现在文档显示了您的新部分（顶部的信息框消失了）。🎉

现在您可以全部翻译它，并在保存文件时查看效果。

不要翻译这些页面¶

🚨 不要翻译

reference/ 下面的文件
release-notes.md
fastapi-people.md
external-links.md
newsletter.md
management-tasks.md
management.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 文档中的代码块中，翻译注释 (# a comment)，但保留其余内容不变。
不要更改包含在“``”中的任何内容（内联代码）。
在以 /// 开头的行中，仅翻译 "... Text ..." 部分。保留其余内容不变。
您可以翻译信息框，例如 /// warning 为 /// warning | Achtung。但不要更改 /// 后的第一个词，它决定了信息框的颜色。
不要更改图像、代码文件、Markdown 文档链接中的路径。
但是，当 Markdown 文档被翻译时，链接到其标题的 #hash-parts 可能发生变化。如果可能，请更新这些链接。
- 使用正则表达式 #[^# ] 在翻译后的文档中搜索此类链接。
- 在所有已翻译成您语言的文档中搜索 your-translated-document.md。例如，VS Code 具有“编辑” ->“在文件中查找”选项。
- 翻译文档时，不要“预翻译”链接到未翻译文档中标题的 #hash-parts。