|
|
|
@ -1,6 +1,6 @@ |
|
|
|
# 开发 - 贡献 |
|
|
|
|
|
|
|
首先，你最好先了解 [帮助 FastAPI 及获取帮助](help-fastapi.md){.internal-link target=_blank}的基本方式。 |
|
|
|
首先，你可能想了解 [帮助 FastAPI 及获取帮助](help-fastapi.md){.internal-link target=_blank}的基本方式。 |
|
|
|
|
|
|
|
## 开发 |
|
|
|
|
|
|
|
@ -84,6 +84,17 @@ $ python -m venv env |
|
|
|
|
|
|
|
如果显示 `pip` 程序文件位于 `env/bin/pip` 则说明激活成功。 🎉 |
|
|
|
|
|
|
|
确保虚拟环境中的 pip 版本是最新的，以避免后续步骤出现错误： |
|
|
|
|
|
|
|
<div class="termy"> |
|
|
|
|
|
|
|
```console |
|
|
|
$ python -m pip install --upgrade pip |
|
|
|
|
|
|
|
---> 100% |
|
|
|
``` |
|
|
|
|
|
|
|
</div> |
|
|
|
|
|
|
|
!!! tip |
|
|
|
每一次你在该环境下使用 `pip` 安装了新软件包时，请再次激活该环境。 |
|
|
|
@ -114,6 +125,11 @@ $ pip install -r requirements.txt |
|
|
|
|
|
|
|
这样，你不必再去重新"安装"你的本地版本即可测试所有更改。 |
|
|
|
|
|
|
|
!!! note "技术细节" |
|
|
|
仅当你使用此项目中的 `requirements.txt` 安装而不是直接使用 `pip install fastapi` 安装时，才会发生这种情况。 |
|
|
|
|
|
|
|
这是因为在 `requirements.txt` 中，本地的 FastAPI 是使用“可编辑” （`-e`）选项安装的 |
|
|
|
|
|
|
|
### 格式化 |
|
|
|
|
|
|
|
你可以运行下面的脚本来格式化和清理所有代码： |
|
|
|
@ -126,91 +142,93 @@ $ bash scripts/format.sh |
|
|
|
|
|
|
|
</div> |
|
|
|
|
|
|
|
它还会自动对所有导入代码进行整理。 |
|
|
|
它还会自动对所有导入代码进行排序整理。 |
|
|
|
|
|
|
|
为了使整理正确进行，你需要在当前环境中安装本地的 FastAPI，即在运行上述段落中的命令时添加 `-e`。 |
|
|
|
|
|
|
|
### 格式化导入 |
|
|
|
## 文档 |
|
|
|
|
|
|
|
首先，请确保按上述步骤设置好环境，这将安装所有需要的依赖。 |
|
|
|
|
|
|
|
还有另一个脚本可以格式化所有导入，并确保你没有未使用的导入代码： |
|
|
|
### 实时文档 |
|
|
|
|
|
|
|
在本地开发时，可以使用该脚本构建站点并检查所做的任何更改，并实时重载： |
|
|
|
|
|
|
|
<div class="termy"> |
|
|
|
|
|
|
|
```console |
|
|
|
$ bash scripts/format-imports.sh |
|
|
|
$ 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 |
|
|
|
``` |
|
|
|
|
|
|
|
</div> |
|
|
|
|
|
|
|
由于它依次运行了多个命令，并修改和还原了许多文件，所以运行时间会更长一些，因此经常地使用 `scripts/format.sh` 然后仅在提交前执行 `scripts/format-imports.sh` 会更好一些。 |
|
|
|
文档服务将运行在 `http://127.0.0.1:8008`。 |
|
|
|
|
|
|
|
## 文档 |
|
|
|
|
|
|
|
首先，请确保按上述步骤设置好环境，这将安装所有需要的依赖。 |
|
|
|
|
|
|
|
文档使用 <a href="https://www.mkdocs.org/" class="external-link" target="_blank">MkDocs</a> 生成。 |
|
|
|
|
|
|
|
并且在 `./scripts/docs.py` 中还有适用的额外工具/脚本来处理翻译。 |
|
|
|
这样，你可以编辑文档 / 源文件并实时查看更改。 |
|
|
|
|
|
|
|
!!! tip |
|
|
|
你不需要去了解 `./scripts/docs.py` 中的代码，只需在命令行中使用它即可。 |
|
|
|
或者你也可以手动执行和该脚本一样的操作 |
|
|
|
|
|
|
|
所有文档均在 `./docs/en/` 目录中以 Markdown 文件格式保存。 |
|
|
|
|
|
|
|
许多的教程章节里包含有代码块。 |
|
|
|
进入语言目录，如果是英文文档，目录则是 `docs/en/`: |
|
|
|
|
|
|
|
在大多数情况下，这些代码块是可以直接运行的真实完整的应用程序。 |
|
|
|
|
|
|
|
实际上，这些代码块不是写在 Markdown 文件内的，它们是位于 `./docs_src/` 目录中的 Python 文件。 |
|
|
|
```console |
|
|
|
$ cd docs/en/ |
|
|
|
``` |
|
|
|
|
|
|
|
生成站点时，这些 Python 文件会被包含/注入到文档中。 |
|
|
|
在该目录执行 `mkdocs` 命令 |
|
|
|
|
|
|
|
### 用于测试的文档 |
|
|
|
```console |
|
|
|
$ mkdocs serve --dev-addr 8008 |
|
|
|
``` |
|
|
|
|
|
|
|
大多数的测试实际上都是针对文档中的示例源文件运行的。 |
|
|
|
#### Typer CLI （可选） |
|
|
|
|
|
|
|
这有助于确保： |
|
|
|
本指引向你展示了如何直接用 `python` 运行 `./scripts/docs.py` 中的脚本。 |
|
|
|
|
|
|
|
* 文档始终是最新的。 |
|
|
|
* 文档示例可以直接运行。 |
|
|
|
* 绝大多数特性既在文档中得以阐述，又通过测试覆盖进行保障。 |
|
|
|
但你也可以使用 <a href="https://typer.tiangolo.com/typer-cli/" class="external-link" target="_blank">Typer CLI</a>，而且在安装了补全功能后，你将可以在终端中对命令进行自动补全。 |
|
|
|
|
|
|
|
在本地开发期间，有一个脚本可以实时重载地构建站点并用来检查所做的任何更改： |
|
|
|
如果你已经安装 Typer CLI ，则可以使用以下命令安装自动补全功能： |
|
|
|
|
|
|
|
<div class="termy"> |
|
|
|
|
|
|
|
```console |
|
|
|
$ python ./scripts/docs.py live |
|
|
|
$ typer --install-completion |
|
|
|
|
|
|
|
<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 |
|
|
|
zsh completion installed in /home/user/.bashrc. |
|
|
|
Completion will take effect once you restart the terminal. |
|
|
|
``` |
|
|
|
|
|
|
|
</div> |
|
|
|
|
|
|
|
它将在 `http://127.0.0.1:8008` 提供对文档的访问。 |
|
|
|
### 文档架构 |
|
|
|
|
|
|
|
这样，你可以编辑文档/源文件并实时查看更改。 |
|
|
|
文档使用 <a href="https://www.mkdocs.org/" class="external-link" target="_blank">MkDocs</a> 生成。 |
|
|
|
|
|
|
|
#### Typer CLI （可选） |
|
|
|
在 `./scripts/docs.py` 中还有额外工具 / 脚本来处理翻译。 |
|
|
|
|
|
|
|
本指引向你展示了如何直接用 `python` 程序运行 `./scripts/docs.py` 中的脚本。 |
|
|
|
!!! tip |
|
|
|
你不需要去了解 `./scripts/docs.py` 中的代码，只需在命令行中使用它即可。 |
|
|
|
|
|
|
|
但你也可以使用 <a href="https://typer.tiangolo.com/typer-cli/" class="external-link" target="_blank">Typer CLI</a>，而且在安装了补全功能后，你将可以在终端中对命令进行自动补全。 |
|
|
|
所有文档均在 `./docs/en/` 目录中以 Markdown 文件格式保存。 |
|
|
|
|
|
|
|
如果你打算安装 Typer CLI ，可以使用以下命令安装自动补全功能： |
|
|
|
许多的教程中都有一些代码块，大多数情况下，这些代码是可以直接运行的，因为这些代码不是写在 Markdown 文件里的，而是写在 `./docs_src/` 目录中的 Python 文件里。 |
|
|
|
|
|
|
|
<div class="termy"> |
|
|
|
在生成站点的时候，这些 Python 文件会被打包进文档中。 |
|
|
|
|
|
|
|
```console |
|
|
|
$ typer --install-completion |
|
|
|
### 测试文档 |
|
|
|
|
|
|
|
zsh completion installed in /home/user/.bashrc. |
|
|
|
Completion will take effect once you restart the terminal. |
|
|
|
``` |
|
|
|
大多数的测试实际上都是针对文档中的示例源文件运行的。 |
|
|
|
|
|
|
|
这有助于确保： |
|
|
|
|
|
|
|
* 文档始终是最新的。 |
|
|
|
* 文档示例可以直接运行。 |
|
|
|
* 绝大多数特性既在文档中得以阐述，又通过测试覆盖进行保障。 |
|
|
|
|
|
|
|
</div> |
|
|
|
|
|
|
|
### 应用和文档同时运行 |
|
|
|
|
|
|
|
@ -230,7 +248,7 @@ $ uvicorn tutorial001:app --reload |
|
|
|
|
|
|
|
### 翻译 |
|
|
|
|
|
|
|
非常感谢你能够参与文档的翻译！这项工作需要社区的帮助才能完成。 🌎 🚀 |
|
|
|
**非常感谢**你能够参与文档的翻译！这项工作需要社区的帮助才能完成。 🌎 🚀 |
|
|
|
|
|
|
|
以下是参与帮助翻译的步骤。 |
|
|
|
|
|
|
|
@ -243,17 +261,19 @@ $ uvicorn tutorial001:app --reload |
|
|
|
|
|
|
|
详情可查看关于 <a href="https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-request-reviews" class="external-link" target="_blank">添加 pull request 评审意见</a> 以同意合并或要求修改的文档。 |
|
|
|
|
|
|
|
* 在 <a href="https://github.com/tiangolo/fastapi/issues" class="external-link" target="_blank">issues</a> 中查找是否有对你所用语言所进行的协作翻译。 |
|
|
|
* 检查在 <a href="https://github.com/tiangolo/fastapi/discussions/categories/translations" class="external-link" target="_blank">GitHub Discussion</a> 是否有关于你所用语言的协作翻译。 如果有，你可以订阅它，当有一条新的 PR 请求需要评审时，系统会自动将其添加到讨论中，你也会收到对应的推送。 |
|
|
|
|
|
|
|
* 每翻译一个页面新增一个 pull request。这将使其他人更容易对其进行评审。 |
|
|
|
|
|
|
|
对于我（译注：作者使用西班牙语和英语）不懂的语言，我将在等待其他人评审翻译之后将其合并。 |
|
|
|
|
|
|
|
* 你还可以查看是否有你所用语言的翻译，并对其进行评审，这将帮助我了解翻译是否正确以及能否将其合并。 |
|
|
|
* 可以在 <a href="https://github.com/tiangolo/fastapi/discussions/categories/translations" class="external-link" target="_blank">GitHub Discussions</a> 中查看。 |
|
|
|
* 也可以在现有 PR 中通过你使用的语言标签来筛选对应的 PR，举个例子，对于西班牙语，标签是 <a href="https://github.com/tiangolo/fastapi/pulls?q=is%3Apr+is%3Aopen+sort%3Aupdated-desc+label%3Alang-es+label%3A%22awaiting+review%22" class="external-link" target="_blank">`lang-es`</a>。 |
|
|
|
|
|
|
|
* 使用相同的 Python 示例并且仅翻译文档中的文本。无需进行任何其他更改示例也能正常工作。 |
|
|
|
* 请使用相同的 Python 示例，且只需翻译文档中的文本，不用修改其它东西。 |
|
|
|
|
|
|
|
* 使用相同的图片、文件名以及链接地址。无需进行任何其他调整来让它们兼容。 |
|
|
|
* 请使用相同的图片、文件名以及链接地址，不用修改其它东西。 |
|
|
|
|
|
|
|
* 你可以从 <a href="https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes" class="external-link" target="_blank">ISO 639-1 代码列表</a> 表中查找你想要翻译语言的两位字母代码。 |
|
|
|
|
|
|
|
@ -264,7 +284,7 @@ $ uvicorn tutorial001:app --reload |
|
|
|
对于西班牙语来说，它的两位字母代码是 `es`。所以西班牙语翻译的目录位于 `docs/es/`。 |
|
|
|
|
|
|
|
!!! tip |
|
|
|
主要（"官方"）语言是英语，位于 `docs/en/`目录。 |
|
|
|
默认语言是英语，位于 `docs/en/`目录。 |
|
|
|
|
|
|
|
现在为西班牙语文档运行实时服务器： |
|
|
|
|
|
|
|
@ -281,11 +301,24 @@ $ python ./scripts/docs.py live es |
|
|
|
|
|
|
|
</div> |
|
|
|
|
|
|
|
现在你可以访问 <a href="http://127.0.0.1:8008" class="external-link" target="_blank">http://127.0.0.1:8008</a> 实时查看你所做的更改。 |
|
|
|
!!! tip |
|
|
|
或者你也可以手动执行和该脚本一样的操作 |
|
|
|
|
|
|
|
如果你查看 FastAPI 的线上文档网站，会看到每种语言都有所有页面。但是某些页面并未被翻译并且会有一处关于缺少翻译的提示。 |
|
|
|
进入语言目录，对于西班牙语的翻译，目录是 `docs/es/`: |
|
|
|
|
|
|
|
但是当你像上面这样在本地运行文档时，你只会看到已经翻译的页面。 |
|
|
|
```console |
|
|
|
$ cd docs/es/ |
|
|
|
``` |
|
|
|
|
|
|
|
在该目录执行 `mkdocs` 命令 |
|
|
|
|
|
|
|
```console |
|
|
|
$ mkdocs serve --dev-addr 8008 |
|
|
|
``` |
|
|
|
|
|
|
|
现在你可以访问 <a href="http://127.0.0.1:8008" class="external-link" target="_blank">http://127.0.0.1:8008</a> 实时查看你所做的更改。 |
|
|
|
|
|
|
|
如果你查看 FastAPI 的线上文档网站，会看到每种语言都有所有的文档页面，但是某些页面并未被翻译并且会有一处关于缺少翻译的提示。（但是当你像上面这样在本地运行文档时，你只会看到已经翻译的页面。） |
|
|
|
|
|
|
|
现在假设你要为 [Features](features.md){.internal-link target=_blank} 章节添加翻译。 |
|
|
|
|
|
|
|
@ -304,49 +337,9 @@ docs/es/docs/features.md |
|
|
|
!!! tip |
|
|
|
注意路径和文件名的唯一变化是语言代码，从 `en` 更改为 `es`。 |
|
|
|
|
|
|
|
* 现在打开位于英语文档目录下的 MkDocs 配置文件： |
|
|
|
回到浏览器你就可以看到刚刚更新的章节了。🎉 |
|
|
|
|
|
|
|
``` |
|
|
|
docs/en/docs/mkdocs.yml |
|
|
|
``` |
|
|
|
|
|
|
|
* 在配置文件中找到 `docs/features.md` 所在的位置。结果像这样： |
|
|
|
|
|
|
|
```YAML hl_lines="8" |
|
|
|
site_name: FastAPI |
|
|
|
# More stuff |
|
|
|
nav: |
|
|
|
- FastAPI: index.md |
|
|
|
- Languages: |
|
|
|
- en: / |
|
|
|
- es: /es/ |
|
|
|
- features.md |
|
|
|
``` |
|
|
|
|
|
|
|
* 打开你正在编辑的语言目录中的 MkDocs 配置文件，例如： |
|
|
|
|
|
|
|
``` |
|
|
|
docs/es/docs/mkdocs.yml |
|
|
|
``` |
|
|
|
|
|
|
|
* 将其添加到与英语文档完全相同的位置，例如： |
|
|
|
|
|
|
|
```YAML hl_lines="8" |
|
|
|
site_name: FastAPI |
|
|
|
# More stuff |
|
|
|
nav: |
|
|
|
- FastAPI: index.md |
|
|
|
- Languages: |
|
|
|
- en: / |
|
|
|
- es: /es/ |
|
|
|
- features.md |
|
|
|
``` |
|
|
|
|
|
|
|
如果配置文件中还有其他条目，请确保你所翻译的新条目和它们之间的顺序与英文版本完全相同。 |
|
|
|
|
|
|
|
打开浏览器，现在你将看到文档展示了你所加入的新章节。 🎉 |
|
|
|
|
|
|
|
现在，你可以将它全部翻译完并在保存文件后进行预览。 |
|
|
|
现在，你可以翻译这些内容并在保存文件后进行预览。 |
|
|
|
|
|
|
|
#### 新语言 |
|
|
|
|
|
|
|
@ -354,7 +347,7 @@ nav: |
|
|
|
|
|
|
|
假设你想要添加克里奥尔语翻译，而且文档中还没有该语言的翻译。 |
|
|
|
|
|
|
|
点击上面提到的链接，可以查到"克里奥尔语"的代码为 `ht`。 |
|
|
|
点击上面提到的“ISO 639-1 代码列表”链接，可以查到“克里奥尔语”的代码为 `ht`。 |
|
|
|
|
|
|
|
下一步是运行脚本以生成新的翻译目录： |
|
|
|
|
|
|
|
@ -365,55 +358,32 @@ nav: |
|
|
|
$ python ./scripts/docs.py new-lang ht |
|
|
|
|
|
|
|
Successfully initialized: docs/ht |
|
|
|
Updating ht |
|
|
|
Updating en |
|
|
|
``` |
|
|
|
|
|
|
|
</div> |
|
|
|
|
|
|
|
现在，你可以在编辑器中查看新创建的目录 `docs/ht/`。 |
|
|
|
|
|
|
|
!!! tip |
|
|
|
在添加实际的翻译之前，仅以此创建首个 pull request 来设定新语言的配置。 |
|
|
|
|
|
|
|
这样当你在翻译第一个页面时，其他人可以帮助翻译其他页面。🚀 |
|
|
|
|
|
|
|
首先翻译文档主页 `docs/ht/index.md`。 |
|
|
|
|
|
|
|
然后，你可以根据上面的"已有语言"的指引继续进行翻译。 |
|
|
|
这条命令会生成一个从 `en` 版本继承了所有属性的配置文件 `docs/ht/mkdocs.yml`: |
|
|
|
|
|
|
|
##### 不支持的新语言 |
|
|
|
|
|
|
|
如果在运行实时服务器脚本时收到关于不支持该语言的错误，类似于： |
|
|
|
|
|
|
|
``` |
|
|
|
raise TemplateNotFound(template) |
|
|
|
jinja2.exceptions.TemplateNotFound: partials/language/xx.html |
|
|
|
```yaml |
|
|
|
INHERIT: ../en/mkdocs.yml |
|
|
|
``` |
|
|
|
|
|
|
|
这意味着文档的主题不支持该语言（在这种例子中，编造的语言代码是 `xx`）。 |
|
|
|
|
|
|
|
但是别担心，你可以将主题语言设置为英语，然后翻译文档的内容。 |
|
|
|
|
|
|
|
如果你需要这么做，编辑新语言目录下的 `mkdocs.yml`，它将有类似下面的内容： |
|
|
|
!!! tip |
|
|
|
你也可以自己手动创建包含这些内容的文件。 |
|
|
|
|
|
|
|
```YAML hl_lines="5" |
|
|
|
site_name: FastAPI |
|
|
|
# More stuff |
|
|
|
theme: |
|
|
|
# More stuff |
|
|
|
language: xx |
|
|
|
``` |
|
|
|
这条命令还会生成一个文档主页 `docs/ht/index.md`，你可以从这个文件开始翻译。 |
|
|
|
|
|
|
|
将其中的 language 项从 `xx`（你的语言代码）更改为 `en`。 |
|
|
|
然后，你可以根据上面的"已有语言"的指引继续进行翻译。 |
|
|
|
|
|
|
|
然后，你就可以再次启动实时服务器了。 |
|
|
|
翻译完成后，你就可以用 `docs/ht/mkdocs.yml` 和 `docs/ht/index.md` 发起 PR 了。🎉 |
|
|
|
|
|
|
|
#### 预览结果 |
|
|
|
|
|
|
|
当你通过 `live` 命令使用 `./scripts/docs.py` 中的脚本时，该脚本仅展示当前语言已有的文件和翻译。 |
|
|
|
你可以执行 `./scripts/docs.py live` 命令来预览结果（或者 `mkdocs serve`）。 |
|
|
|
|
|
|
|
但是当你完成翻译后，你可以像在线上展示一样测试所有内容。 |
|
|
|
但是当你完成翻译后，你可以像在线上展示一样测试所有内容，包括所有其他语言。 |
|
|
|
|
|
|
|
为此，首先构建所有文档： |
|
|
|
|
|
|
|
@ -423,19 +393,16 @@ theme: |
|
|
|
// Use the command "build-all", this will take a bit |
|
|
|
$ python ./scripts/docs.py build-all |
|
|
|
|
|
|
|
Updating es |
|
|
|
Updating en |
|
|
|
Building docs for: en |
|
|
|
Building docs for: es |
|
|
|
Successfully built docs for: es |
|
|
|
Copying en index.md to README.md |
|
|
|
``` |
|
|
|
|
|
|
|
</div> |
|
|
|
|
|
|
|
这将在 `./docs_build/` 目录中为每一种语言生成全部的文档。还包括添加所有缺少翻译的文件，并带有一条"此文件还没有翻译"的提醒。但是你不需要对该目录执行任何操作。 |
|
|
|
这样会对每一种语言构建一个独立的文档站点，并最终把这些站点全部打包输出到 `./site/` 目录。 |
|
|
|
|
|
|
|
|
|
|
|
然后，它针对每种语言构建独立的 MkDocs 站点，将它们组合在一起，并在 `./site/` 目录中生成最终的输出。 |
|
|
|
|
|
|
|
然后你可以使用命令 `serve` 来运行生成的站点： |
|
|
|
|
|
|
|
|
Aruelius.L
1 year ago
GitHub