diff --git a/docs/ru/docs/contributing.md b/docs/ru/docs/contributing.md deleted file mode 100644 index a4c9301849..0000000000 --- a/docs/ru/docs/contributing.md +++ /dev/null @@ -1,260 +0,0 @@ -# Разработка - Вклад - -Для начала вам, возможно, захочется ознакомиться с основными способами [помочь проекту FastAPI и получить помощь](help-fastapi.md). - -## Разработка - -Если вы уже клонировали [репозиторий fastapi](https://github.com/fastapi/fastapi) и вы хотите глубоко погрузиться в код, вот несколько рекомендаций по настройке вашего окружения. - -### Установка зависимостей - -Создайте виртуальное окружение и установите необходимые пакеты с помощью [uv](https://github.com/astral-sh/uv): - -
- -```console -$ uv sync --extra all - ----> 100% -``` - -
- -Это установит все зависимости и вашу локальную версию FastAPI в локальное окружение. - -### Использование вашей локальной версии FastAPI - -Если вы создадите Python-файл, который импортирует и использует FastAPI, и запустите его с помощью Python из вашего локального окружения, он будет использовать клонированный вами локальный исходный код FastAPI. - -И если вы обновите этот локальной исходный код FastAPI, то при повторном запуске того же Python-файла будет использоваться свежая версия FastAPI, которую вы только что отредактировали. - -Таким образом, вам не нужно "устанавливать" вашу локальную версию, чтобы иметь возможность тестировать каждое изменение. - -/// note | Технические детали - -Это происходит только в том случае, если вы устанавливаете зависимость с помощью `uv sync --extra all`, а не запускаете `pip install fastapi` напрямую. - -Это связанно с тем, что `uv sync --extra all` по умолчанию устанавливает локальную версию FastAPI в "редактируемом (editable)" режиме. - -/// - -### Форматирование кода - -Существует скрипт, который вы можете запустить для форматирования и очистки всего вашего кода: - -
- -```console -$ bash scripts/format.sh -``` - -
- -Он также автоматически отсортирует все ваши импорты. - -## Тестирование - -Существует скрипт, который вы можете запустить локально для тестирования всего кода и создания отчетов о покрытии в формате HTML: - -
- -```console -$ bash scripts/test-cov-html.sh -``` - -
- -Эта команда создает директорию `./htmlcov/`. Если вы откроете файл `./htmlcov/index.html` в вашем браузере, вы сможете в интерактивном режиме изучить участки кода, которые покрыты тестами, если какие-то участки пропущены. - -## Документация - -Сначала убедитесь, что вы настроили свое окружение, как описано выше - это установит все необходимые зависимости. - -### Документация в реальном времени - -Во время локальной разработки существует скрипт, которые собирает сайт и отслеживает любые изменения с автоматической перезагрузкой. - -
- -```console -$ python ./scripts/docs.py live - -[INFO] Serving on http://127.0.0.1:8008 -[INFO] Start watching changes -[INFO] Start detecting changes -``` - -
- -Он запустит документацию по адресу `http://127.0.0.1:8008`. - -Таким образом, вы можете редактировать файлы документации/исходного кода и видеть изменения в реальном времени. - -/// tip | Совет - -Как вариант, вы можете вручную выполнить те же шаги, что и скрипт. - -Перейдите в директорию с языком, для основной документации на английском это `docs/en/`: - -```console -$ cd docs/en/ -``` -Затем запустите `mkdocs` в этой директории: - -```console -$ mkdocs serve --dev-addr 127.0.0.1:8008 -``` - -/// - -#### Typer CLI (опционально) - -Инструкции здесь показывают, как использовать скрипт `./scripts/docs.py` напрямую с программой `python`. - -Но вы также можете использовать [Typer CLI](https://typer.tiangolo.com/typer-cli/). После установки этой программы в вашем терминале появится автозавершение команд. - -Если вы установите Typer CLI, вы можете установить автодополнение с помощью: - -
- -```console -$ typer --install-completion - -zsh completion installed in /home/user/.bashrc. -Completion will take effect once you restart the terminal. -``` - -
- -### Структура документации - -Документация использует [MkDocs](https://www.mkdocs.org/). - -А также есть дополнительные инструменты/скрипты для работы с переводами в `./scripts/docs.py`. - -/// tip | Совет - -Вам не нужно изучать код в `./scripts/docs.py`, вы просто используете его из командной строки. - -/// - -Вся документация находится в формате Markdown в директории `./docs/en/`. - -Многие из руководств содержат блоки кода. - -В большинстве случаев эти блоки кода представляют собой полноценные приложения, которые можно запускать как есть. - -На самом деле эти блоки кода не написаны внутри Markdown, они представляют собой Python-файлы в директории `./docs_src/`. - -И эти Python-файлы включаются/внедряются в документацию при генерации сайта. - -### Документация для тестов - -Большинство тестов на самом деле выполняются на примерах исходных файлов из документации. - -Это помогает убедиться в том, что: - -* Документация актуальна. -* Примеры из документации можно запускать как есть. -* Большинство функций покрыто документацией, что подтверждается покрытием тестами. - -#### Приложения и документация одновременно - -Если вы запускаете примеры, например: - -
- -```console -$ fastapi dev tutorial001.py - -INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) -``` - -
- -Поскольку Uvicorn по умолчанию использует порт 8000, документация на порту 8008 не будет конфликтовать. - -### Переводы - -Помощь с переводом ОЧЕНЬ ценится! И она невозможно без помощи сообщества. 🌎 🚀 - -Pull Request`ы с переводами создаются с помощью LLM, управляемых промптами, разработанными командой FastAPI совместно с сообществом носителей языка для каждого поддерживаемого языка. - -#### Промпт LLM для каждого языка - -У каждого языка есть своя директория: [https://github.com/fastapi/fastapi/tree/master/docs](https://github.com/fastapi/fastapi/tree/master/docs). В ней вы можете найти файл `llm-prompt.md` с промптом, специфичным для этого языка. - -Например, для испанского языка промпт находится здесь: [`docs/es/llm-prompt.md`](https://github.com/fastapi/fastapi/blob/master/docs/es/llm-prompt.md). - -Если вы заметите ошибки в вашем языке, вы можете предложить изменения в этом файле для вашего языка и запросить повторную генерацию конкретных страниц после внесения изменений. - -#### Проверка PR с переводами - -Вы также можете просмотреть существующие на данный момент [pull request](https://github.com/fastapi/fastapi/pulls) для вашего языка. Вы можете отфильтровать pull request по метке, соответствующей вашему языку. Например, для испанского языка метка — [`lang-es`](https://github.com/fastapi/fastapi/pulls?q=is%3Aopen+sort%3Aupdated-desc+label%3Alang-es+label%3Aawaiting-review). - -При проверке pull request лучше не предлагать изменения в том же самом pull request, поскольку он создан LLM, и невозможно гарантировать, что небольшие индивидуальные правки будут воспроизведены в других похожих разделах или сохранятся при повторном переводе того же самого содержимого. - -Вместо добавления предложений в PR с переводом, внесите предложения в файл промпта LLM для этого языка в новом PR. Например, для испанского языка файл промпта LLM находится здесь: [`docs/es/llm-prompt.md`](https://github.com/fastapi/fastapi/blob/master/docs/es/llm-prompt.md). - -/// tip | Совет - -Ознакомьтесь с документацией о [добавлении ревью pull request](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-request-reviews), чтобы одобрить его или запросить изменения. - -/// - -#### Подпишитесь на уведомления для вашего языка - -Проверьте, существует ли [GitHub Discussion](https://github.com/fastapi/fastapi/discussions/categories/translations) для координации переводов на ваш язык. Вы можете подписаться на него, и когда появится новый pull request, требующий проверки, автоматический комментарий будет добавлен в обсуждение. - -Чтобы узнать двухбуквенный код для языка, который вы хотите перевести, вы можете воспользоваться таблицей [Список кодов ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes). - -#### Запрос нового языка - -Допустим, вы хотите запросить переводы для языка, который еще не переведен, даже частично. Например, для латыни. - -* Первым шагом вам нужно найти еще двух человек, которые согласились бы проверять PR с переводами на этот язык вместе с вами. -* Как только наберется не менее трех человек, готовых взять на себя обязательство помогать поддерживать этот язык, вы можете переходить к следующим шагам. -* Создайте новое обсуждение, следуя шаблону. -* Отметьте двух других людей, которые будут помогать с языком, и попросите их подтвердить в обсуждении, что они готовы помогать. - -Как только в обсуждении появится несколько человек, команда FastAPI сможет его оценить и сделать перевод официальным. - -Затем документация будет автоматически переводиться с использованием LLM, а команда носителей языка сможет проверять перевод и помогать настраивать промпты для LLM. - -Когда появится новый перевод (например, если документация обновится или добавится новый раздел), в том же обсуждении будет добавлен комментарий со ссылкой на новый перевод для проверки. - -## Автоматизированный код и ИИ - -Мы приветствуем использование любых инструментов, которые вы хотите применять для своей работы и максимально эффективного участия в проекте, включая инструменты на основе ИИ (LLM) и другие. Тем не менее, вклад должен подразумевать осмысленное человеческое вмешательство, суждение, контекст и т.п. - -Если **человеческих усилий**, вложенных в PR (например, написание промптов для LLM), **меньше**, чем **усилий, которые нам потребуется затратить** на его **проверку**, пожалуйста, **не** отправляйте такой PR. - -Подумайте об этом так: мы и сами можем писать промпты для LLM или запускать автоматизированные инструменты, и это будет быстрее, чем проверять внешние PR. - -### Закрытие автоматизированных PR и PR, созданных с помощью ИИ - -Если мы увидим PR, которые выглядят как сгенерированные ИИ или автоматизированные подобным образом, мы пометим их и закроем. - -Тоже самое относится к комментариям и описаниям - пожалуйста, не копируйте содержимое, сгенерированное LLM. - -### Отказ в обслуживании человеческих усилий - -Использование автоматизированных инструментов и ИИ для отправки PR или комментариев, которые нам приходится тщательно проверять и обрабатывать, было бы равносильно [атаке типа «отказ в обслуживании»](https://en.wikipedia.org/wiki/Denial-of-service_attack) на наши человеческие усилия. - -Это потребовало бы очень мало усилий со стороны человека, отправляющего PR (один промпт для LLM), но порождало бы большой объем работы с нашей стороны (тщательная проверка кода). - -Пожалуйста, не делайте этого. - -Нам придется блокировать аккаунты, которые спамят нас повторяющимися автоматизированными PR или комментариями. - -### Используйте инструменты с умом - -Как говорил дядя Бен: - -
-С большой силой инструментами приходит большая ответственность. -
- -Избегайте случайного вреда. - -У вас есть удивительные инструменты, используйте их с умом, чтобы помогать эффективно.