Browse Source
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>pull/5971/head
Vladislav Kramorenko
2 years ago
committed by
GitHub
GitHub
2 changed files with 470 additions and 0 deletions
@ -0,0 +1,469 @@ |
|||||
|
# Участие в разработке фреймворка |
||||
|
|
||||
|
Возможно, для начала Вам стоит ознакомиться с основными способами [помочь FastAPI или получить помощь](help-fastapi.md){.internal-link target=_blank}. |
||||
|
|
||||
|
## Разработка |
||||
|
|
||||
|
Если Вы уже склонировали репозиторий и знаете, что Вам нужно более глубокое погружение в код фреймворка, то здесь представлены некоторые инструкции по настройке виртуального окружения. |
||||
|
|
||||
|
### Виртуальное окружение с помощью `venv` |
||||
|
|
||||
|
Находясь в нужной директории, Вы можете создать виртуальное окружение при помощи Python модуля `venv`. |
||||
|
|
||||
|
<div class="termy"> |
||||
|
|
||||
|
```console |
||||
|
$ python -m venv env |
||||
|
``` |
||||
|
|
||||
|
</div> |
||||
|
|
||||
|
Эта команда создаст директорию `./env/` с бинарными (двоичными) файлами Python, а затем Вы сможете скачивать и устанавливать необходимые библиотеки в изолированное виртуальное окружение. |
||||
|
|
||||
|
### Активация виртуального окружения |
||||
|
|
||||
|
Активируйте виртуально окружение командой: |
||||
|
|
||||
|
=== "Linux, macOS" |
||||
|
|
||||
|
<div class="termy"> |
||||
|
|
||||
|
```console |
||||
|
$ source ./env/bin/activate |
||||
|
``` |
||||
|
|
||||
|
</div> |
||||
|
|
||||
|
=== "Windows PowerShell" |
||||
|
|
||||
|
<div class="termy"> |
||||
|
|
||||
|
```console |
||||
|
$ .\env\Scripts\Activate.ps1 |
||||
|
``` |
||||
|
|
||||
|
</div> |
||||
|
|
||||
|
=== "Windows Bash" |
||||
|
|
||||
|
Если Вы пользуетесь Bash для Windows (например: <a href="https://gitforwindows.org/" class="external-link" target="_blank">Git Bash</a>): |
||||
|
|
||||
|
<div class="termy"> |
||||
|
|
||||
|
```console |
||||
|
$ source ./env/Scripts/activate |
||||
|
``` |
||||
|
|
||||
|
</div> |
||||
|
|
||||
|
Проверьте, что всё сработало: |
||||
|
|
||||
|
=== "Linux, macOS, Windows Bash" |
||||
|
|
||||
|
<div class="termy"> |
||||
|
|
||||
|
```console |
||||
|
$ which pip |
||||
|
|
||||
|
some/directory/fastapi/env/bin/pip |
||||
|
``` |
||||
|
|
||||
|
</div> |
||||
|
|
||||
|
=== "Windows PowerShell" |
||||
|
|
||||
|
<div class="termy"> |
||||
|
|
||||
|
```console |
||||
|
$ Get-Command pip |
||||
|
|
||||
|
some/directory/fastapi/env/bin/pip |
||||
|
``` |
||||
|
|
||||
|
</div> |
||||
|
|
||||
|
Ели в терминале появится ответ, что бинарник `pip` расположен по пути `.../env/bin/pip`, значит всё в порядке. 🎉 |
||||
|
|
||||
|
Во избежание ошибок в дальнейших шагах, удостоверьтесь, что в Вашем виртуальном окружении установлена последняя версия `pip`: |
||||
|
|
||||
|
<div class="termy"> |
||||
|
|
||||
|
```console |
||||
|
$ python -m pip install --upgrade pip |
||||
|
|
||||
|
---> 100% |
||||
|
``` |
||||
|
|
||||
|
</div> |
||||
|
|
||||
|
!!! tip "Подсказка" |
||||
|
Каждый раз, перед установкой новой библиотеки в виртуальное окружение при помощи `pip`, не забудьте активировать это виртуальное окружение. |
||||
|
|
||||
|
Это гарантирует, что если Вы используете библиотеку, установленную этим пакетом, то Вы используете библиотеку из Вашего локального окружения, а не любую другую, которая может быть установлена глобально. |
||||
|
|
||||
|
### pip |
||||
|
|
||||
|
После активации виртуального окружения, как было указано ранее, введите следующую команду: |
||||
|
|
||||
|
<div class="termy"> |
||||
|
|
||||
|
```console |
||||
|
$ pip install -e ."[dev,doc,test]" |
||||
|
|
||||
|
---> 100% |
||||
|
``` |
||||
|
|
||||
|
</div> |
||||
|
|
||||
|
Это установит все необходимые зависимости в локальное окружение для Вашего локального FastAPI. |
||||
|
|
||||
|
#### Использование локального FastAPI |
||||
|
|
||||
|
Если Вы создаёте Python файл, который импортирует и использует FastAPI,а затем запускаете его интерпретатором Python из Вашего локального окружения, то он будет использовать код из локального FastAPI. |
||||
|
|
||||
|
И, так как при вводе вышеупомянутой команды был указан флаг `-e`, если Вы измените код локального FastAPI, то при следующем запуске этого файла, он будет использовать свежую версию локального FastAPI, который Вы только что изменили. |
||||
|
|
||||
|
Таким образом, Вам не нужно "переустанавливать" Вашу локальную версию, чтобы протестировать каждое изменение. |
||||
|
|
||||
|
### Форматировние |
||||
|
|
||||
|
Скачанный репозиторий содержит скрипт, который может отформатировать и подчистить Ваш код: |
||||
|
|
||||
|
<div class="termy"> |
||||
|
|
||||
|
```console |
||||
|
$ bash scripts/format.sh |
||||
|
``` |
||||
|
|
||||
|
</div> |
||||
|
|
||||
|
Заодно он упорядочит Ваши импорты. |
||||
|
|
||||
|
Чтобы он сортировал их правильно, необходимо, чтобы FastAPI был установлен локально в Вашей среде, с помощью команды из раздела выше, использующей флаг `-e`. |
||||
|
|
||||
|
## Документация |
||||
|
|
||||
|
Прежде всего, убедитесь, что Вы настроили своё окружение, как описано выше, для установки всех зависимостей. |
||||
|
|
||||
|
Документация использует <a href="https://www.mkdocs.org/" class="external-link" target="_blank">MkDocs</a>. |
||||
|
|
||||
|
Также существуют дополнительные инструменты/скрипты для работы с переводами в `./scripts/docs.py`. |
||||
|
|
||||
|
!!! tip "Подсказка" |
||||
|
|
||||
|
Нет необходимости заглядывать в `./scripts/docs.py`, просто используйте это в командной строке. |
||||
|
|
||||
|
Вся документация имеет формат Markdown и расположена в директории `./docs/en/`. |
||||
|
|
||||
|
Многие руководства содержат блоки кода. |
||||
|
|
||||
|
В большинстве случаев эти блоки кода представляют собой вполне законченные приложения, которые можно запускать как есть. |
||||
|
|
||||
|
На самом деле, эти блоки кода не написаны внутри Markdown, это Python файлы в директории `./docs_src/`. |
||||
|
|
||||
|
И эти Python файлы включаются/вводятся в документацию при создании сайта. |
||||
|
|
||||
|
### Тестирование документации |
||||
|
|
||||
|
|
||||
|
Фактически, большинство тестов запускаются с примерами исходных файлов в документации. |
||||
|
|
||||
|
Это помогает убедиться, что: |
||||
|
|
||||
|
* Документация находится в актуальном состоянии. |
||||
|
* Примеры из документации могут быть запущены как есть. |
||||
|
* Большинство функций описаны в документации и покрыты тестами. |
||||
|
|
||||
|
Существует скрипт, который во время локальной разработки создаёт сайт и проверяет наличие любых изменений, перезагружая его в реальном времени: |
||||
|
|
||||
|
<div class="termy"> |
||||
|
|
||||
|
```console |
||||
|
$ 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> |
||||
|
|
||||
|
Он запустит сайт документации по адресу: `http://127.0.0.1:8008`. |
||||
|
|
||||
|
|
||||
|
Таким образом, Вы сможете редактировать файлы с документацией или кодом и наблюдать изменения вживую. |
||||
|
|
||||
|
#### Typer CLI (опционально) |
||||
|
|
||||
|
|
||||
|
Приведенная ранее инструкция показала Вам, как запускать скрипт `./scripts/docs.py` непосредственно через интерпретатор `python` . |
||||
|
|
||||
|
Но также можно использовать <a href="https://typer.tiangolo.com/typer-cli/" class="external-link" target="_blank">Typer CLI</a>, что позволит Вам воспользоваться автозаполнением команд в Вашем терминале. |
||||
|
|
||||
|
Если Вы установили Typer CLI, то для включения функции автозаполнения, введите эту команду: |
||||
|
|
||||
|
<div class="termy"> |
||||
|
|
||||
|
```console |
||||
|
$ typer --install-completion |
||||
|
|
||||
|
zsh completion installed in /home/user/.bashrc. |
||||
|
Completion will take effect once you restart the terminal. |
||||
|
``` |
||||
|
|
||||
|
</div> |
||||
|
|
||||
|
### Приложения и документация одновременно |
||||
|
|
||||
|
Если Вы запускаете приложение, например так: |
||||
|
|
||||
|
<div class="termy"> |
||||
|
|
||||
|
```console |
||||
|
$ uvicorn tutorial001:app --reload |
||||
|
|
||||
|
<span style="color: green;">INFO</span>: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) |
||||
|
``` |
||||
|
|
||||
|
</div> |
||||
|
|
||||
|
По умолчанию Uvicorn будет использовать порт `8000` и не будет конфликтовать с сайтом документации, использующим порт `8008`. |
||||
|
|
||||
|
### Переводы на другие языки |
||||
|
|
||||
|
Помощь с переводами ценится КРАЙНЕ ВЫСОКО! И переводы не могут быть сделаны без помощи сообщества. 🌎 🚀 |
||||
|
|
||||
|
Ниже приведены шаги, как помочь с переводами. |
||||
|
|
||||
|
#### Подсказки и инструкции |
||||
|
|
||||
|
* Проверьте <a href="https://github.com/tiangolo/fastapi/pulls" class="external-link" target="_blank">существующие пул-реквесты</a> для Вашего языка. Добавьте отзывы с просьбой внести изменения, если они необходимы, или одобрите их. |
||||
|
|
||||
|
!!! tip "Подсказка" |
||||
|
Вы можете <a href="https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/commenting-on-a-pull-request" class="external-link" target="_blank">добавлять комментарии с предложениями по изменению</a> в существующие пул-реквесты. |
||||
|
|
||||
|
Ознакомьтесь с документацией о <a href="https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-request-reviews" class="external-link" target="_blank">добавлении отзыва к пул-реквесту</a>, чтобы утвердить его или запросить изменения. |
||||
|
|
||||
|
* Проверьте <a href="https://github.com/tiangolo/fastapi/issues" class="external-link" target="_blank">проблемы и вопросы</a>, чтобы узнать, есть ли кто-то, координирующий переводы для Вашего языка. |
||||
|
|
||||
|
* Добавляйте один пул-реквест для каждой отдельной переведённой страницы. Это значительно облегчит другим его просмотр. |
||||
|
|
||||
|
Для языков, которые я не знаю, прежде чем добавить перевод в основную ветку, я подожду пока несколько других участников сообщества проверят его. |
||||
|
|
||||
|
* Вы также можете проверить, есть ли переводы для Вашего языка и добавить к ним отзыв, который поможет мне убедиться в правильности перевода. Тогда я смогу объединить его с основной веткой. |
||||
|
|
||||
|
* Используйте те же самые примеры кода Python. Переводите только текст документации. Вам не нужно ничего менять, чтобы эти примеры работали. |
||||
|
|
||||
|
* Используйте те же самые изображения, имена файлов и ссылки. Вы не должны менять ничего для сохранения работоспособности. |
||||
|
|
||||
|
* Чтобы узнать 2-буквенный код языка, на который Вы хотите сделать перевод, Вы можете воспользоваться таблицей <a href="https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes" class="external-link" target="_blank">Список кодов языков ISO 639-1</a>. |
||||
|
|
||||
|
#### Существующий язык |
||||
|
|
||||
|
Допустим, Вы хотите перевести страницу на язык, на котором уже есть какие-то переводы, например, на испанский. |
||||
|
|
||||
|
Кодом испанского языка является `es`. А значит директория для переводов на испанский язык: `docs/es/`. |
||||
|
|
||||
|
!!! tip "Подсказка" |
||||
|
Главный ("официальный") язык - английский, директория для него `docs/en/`. |
||||
|
|
||||
|
Вы можете запустить сервер документации на испанском: |
||||
|
|
||||
|
<div class="termy"> |
||||
|
|
||||
|
```console |
||||
|
// Используйте команду "live" и передайте код языка в качестве аргумента командной строки |
||||
|
$ 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 |
||||
|
``` |
||||
|
|
||||
|
</div> |
||||
|
|
||||
|
Теперь Вы можете перейти по адресу: <a href="http://127.0.0.1:8008" class="external-link" target="_blank">http://127.0.0.1:8008</a> и наблюдать вносимые Вами изменения вживую. |
||||
|
|
||||
|
|
||||
|
Если Вы посмотрите на сайт документации FastAPI, то увидите, что все страницы есть на каждом языке. Но некоторые страницы не переведены и имеют уведомление об отсутствующем переводе. |
||||
|
|
||||
|
Но когда Вы запускаете сайт локально, Вы видите только те страницы, которые уже переведены. |
||||
|
|
||||
|
|
||||
|
Предположим, что Вы хотите добавить перевод страницы [Основные свойства](features.md){.internal-link target=_blank}. |
||||
|
|
||||
|
* Скопируйте файл: |
||||
|
|
||||
|
``` |
||||
|
docs/en/docs/features.md |
||||
|
``` |
||||
|
|
||||
|
* Вставьте его точно в то же место, но в директорию языка, на который Вы хотите сделать перевод, например: |
||||
|
|
||||
|
``` |
||||
|
docs/es/docs/features.md |
||||
|
``` |
||||
|
|
||||
|
!!! tip "Подсказка" |
||||
|
Заметьте, что в пути файла мы изменили только код языка с `en` на `es`. |
||||
|
|
||||
|
* Теперь откройте файл конфигурации MkDocs для английского языка, расположенный тут: |
||||
|
|
||||
|
``` |
||||
|
docs/en/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/mkdocs.yml |
||||
|
``` |
||||
|
|
||||
|
* Добавьте строку `docs/features.md` точно в то же место, как и в случае для английского, как-то так: |
||||
|
|
||||
|
```YAML hl_lines="8" |
||||
|
site_name: FastAPI |
||||
|
# More stuff |
||||
|
nav: |
||||
|
- FastAPI: index.md |
||||
|
- Languages: |
||||
|
- en: / |
||||
|
- es: /es/ |
||||
|
- features.md |
||||
|
``` |
||||
|
|
||||
|
Убедитесь, что при наличии других записей, новая запись с Вашим переводом находится точно в том же порядке, что и в английской версии. |
||||
|
|
||||
|
Если Вы зайдёте в свой браузер, то увидите, что в документации стал отображаться Ваш новый раздел.🎉 |
||||
|
|
||||
|
Теперь Вы можете переводить эту страницу и смотреть, как она выглядит при сохранении файла. |
||||
|
|
||||
|
#### Новый язык |
||||
|
|
||||
|
Допустим, Вы хотите добавить перевод для языка, на который пока что не переведена ни одна страница. |
||||
|
|
||||
|
Скажем, Вы решили сделать перевод для креольского языка, но его еще нет в документации. |
||||
|
|
||||
|
Перейдите в таблицу кодов языков по ссылке указанной выше, где найдёте, что кодом креольского языка является `ht`. |
||||
|
|
||||
|
Затем запустите скрипт, генерирующий директорию для переводов на новые языки: |
||||
|
|
||||
|
<div class="termy"> |
||||
|
|
||||
|
```console |
||||
|
// Используйте команду new-lang и передайте код языка в качестве аргумента командной строки |
||||
|
$ python ./scripts/docs.py new-lang ht |
||||
|
|
||||
|
Successfully initialized: docs/ht |
||||
|
Updating ht |
||||
|
Updating en |
||||
|
``` |
||||
|
|
||||
|
</div> |
||||
|
|
||||
|
После чего Вы можете проверить в своем редакторе кода, что появился новый каталог `docs/ht/`. |
||||
|
|
||||
|
!!! tip "Подсказка" |
||||
|
Создайте первый пул-реквест, который будет содержать только пустую директорию для нового языка, прежде чем добавлять переводы. |
||||
|
|
||||
|
Таким образом, другие участники могут переводить другие страницы, пока Вы работаете над одной. 🚀 |
||||
|
|
||||
|
Начните перевод с главной страницы `docs/ht/index.md`. |
||||
|
|
||||
|
В дальнейшем можно действовать, как указано в предыдущих инструкциях для "существующего языка". |
||||
|
|
||||
|
##### Новый язык не поддерживается |
||||
|
|
||||
|
Если при запуске скрипта `./scripts/docs.py live` Вы получаете сообщение об ошибке, что язык не поддерживается, что-то вроде: |
||||
|
|
||||
|
``` |
||||
|
raise TemplateNotFound(template) |
||||
|
jinja2.exceptions.TemplateNotFound: partials/language/xx.html |
||||
|
``` |
||||
|
|
||||
|
Сие означает, что тема не поддерживает этот язык (в данном случае с поддельным 2-буквенным кодом `xx`). |
||||
|
|
||||
|
Но не стоит переживать. Вы можете установить языком темы английский, а затем перевести текст документации. |
||||
|
|
||||
|
Если возникла такая необходимость, отредактируйте `mkdocs.yml` для Вашего нового языка. Это будет выглядеть как-то так: |
||||
|
|
||||
|
```YAML hl_lines="5" |
||||
|
site_name: FastAPI |
||||
|
# More stuff |
||||
|
theme: |
||||
|
# More stuff |
||||
|
language: xx |
||||
|
``` |
||||
|
|
||||
|
Измените `xx` (код Вашего языка) на `en` и перезапустите сервер. |
||||
|
|
||||
|
#### Предпросмотр результата |
||||
|
|
||||
|
Когда Вы запускаете скрипт `./scripts/docs.py` с командой `live`, то будут показаны файлы и переводы для указанного языка. |
||||
|
|
||||
|
Но когда Вы закончите, то можете посмотреть, как это будет выглядеть по-настоящему. |
||||
|
|
||||
|
Для этого сначала создайте всю документацию: |
||||
|
|
||||
|
<div class="termy"> |
||||
|
|
||||
|
```console |
||||
|
// Используйте команду "build-all", это займёт немного времени |
||||
|
$ 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/` для каждого языка. Он добавит все файлы с отсутствующими переводами с пометкой о том, что "у этого файла еще нет перевода". Но Вам не нужно ничего делать с этим каталогом. |
||||
|
|
||||
|
Затем он создаст независимые сайты MkDocs для каждого языка, объединит их и сгенерирует конечный результат на `./site/`. |
||||
|
|
||||
|
После чего Вы сможете запустить сервер со всеми языками командой `serve`: |
||||
|
|
||||
|
<div class="termy"> |
||||
|
|
||||
|
```console |
||||
|
// Используйте команду "serve" после того, как отработает команда "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 |
||||
|
``` |
||||
|
|
||||
|
</div> |
||||
|
|
||||
|
## Тесты |
||||
|
|
||||
|
Также в репозитории есть скрипт, который Вы можете запустить локально, чтобы протестировать весь код и сгенерировать отчеты о покрытии тестами в HTML: |
||||
|
|
||||
|
<div class="termy"> |
||||
|
|
||||
|
```console |
||||
|
$ bash scripts/test-cov-html.sh |
||||
|
``` |
||||
|
|
||||
|
</div> |
||||
|
|
||||
|
Эта команда создаст директорию `./htmlcov/`, в которой будет файл `./htmlcov/index.html`. Открыв его в Вашем браузере, Вы можете в интерактивном режиме изучить, все ли части кода охвачены тестами. |
||||
Loading…
Reference in new issue