From 9ac24926afe34de26cd5a3c5bd08ff00d282a2b9 Mon Sep 17 00:00:00 2001 From: kolo Date: Mon, 20 Oct 2025 16:38:17 +0300 Subject: [PATCH] docs --- .../en/LC_MESSAGES/root/code_of_conduct.po | 166 +++++ .../en/LC_MESSAGES/root/contributing.po | 634 +++++++++++++++++- .../LC_MESSAGES/root/dependency_injection.po | 106 ++- .../en/LC_MESSAGES/root/error_handling.po | 122 ++-- docs/locales/en/LC_MESSAGES/root/flags.po | 98 ++- .../LC_MESSAGES/root/overriding_formatting.po | 91 ++- .../locales/en/LC_MESSAGES/root/quickstart.po | 13 +- .../en/LC_MESSAGES/root/redirect_stdout.po | 199 +++++- docs/root/api/app/index.rst | 96 ++- docs/root/api/command/flags.rst | 10 +- docs/root/api/index.rst | 18 +- docs/root/contributing.rst | 4 +- mock/mock_app/routers.py | 3 +- 13 files changed, 1490 insertions(+), 70 deletions(-) create mode 100644 docs/locales/en/LC_MESSAGES/root/code_of_conduct.po diff --git a/docs/locales/en/LC_MESSAGES/root/code_of_conduct.po b/docs/locales/en/LC_MESSAGES/root/code_of_conduct.po new file mode 100644 index 0000000..fa4909b --- /dev/null +++ b/docs/locales/en/LC_MESSAGES/root/code_of_conduct.po @@ -0,0 +1,166 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2025, kolo +# This file is distributed under the same license as the Argenta package. +# FIRST AUTHOR , 2025. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Argenta \n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-10-20 14:52+0300\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language: en\n" +"Language-Team: en \n" +"Plural-Forms: nplurals=2; plural=(n != 1);\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=utf-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Generated-By: Babel 2.17.0\n" + +#: ../../root/code_of_conduct.rst:4 +msgid "Правила сообщества" +msgstr "" + +#: ../../root/code_of_conduct.rst:7 +msgid "Наше обязательство" +msgstr "" + +#: ../../root/code_of_conduct.rst:9 +msgid "" +"В стремлении создать открытую и приветливую атмосферу, мы, как участники " +"и мейнтейнеры, обязуемся сделать участие в нашем проекте и сообществе " +"свободным от преследований для всех, независимо от возраста, " +"телосложения, инвалидности, этнической принадлежности, половых " +"характеристик, уровня опыта, образования, социально-экономического " +"статуса, национальности, внешности, расы и религии." +msgstr "" + +#: ../../root/code_of_conduct.rst:18 +msgid "Наши стандарты" +msgstr "" + +#: ../../root/code_of_conduct.rst:20 +msgid "" +"Примеры поведения, способствующего созданию позитивной среды для нашего " +"сообщества, включают:" +msgstr "" + +#: ../../root/code_of_conduct.rst:23 +msgid "Проявление эмпатии и доброты по отношению к другим людям." +msgstr "" + +#: ../../root/code_of_conduct.rst:24 +msgid "Уважительное отношение к различным мнениям, точкам зрения и опыту." +msgstr "" + +#: ../../root/code_of_conduct.rst:25 +msgid "Предоставление и тактичное принятие конструктивной обратной связи." +msgstr "" + +#: ../../root/code_of_conduct.rst:26 +msgid "" +"Принятие ответственности, извинения перед теми, кого затронули наши " +"ошибки, и извлечение уроков из этого опыта." +msgstr "" + +#: ../../root/code_of_conduct.rst:28 +msgid "" +"Сосредоточение на том, что лучше не только для нас как отдельных " +"личностей, но и для всего сообщества в целом." +msgstr "" + +#: ../../root/code_of_conduct.rst:31 +msgid "Примеры недопустимого поведения включают:" +msgstr "" + +#: ../../root/code_of_conduct.rst:33 +msgid "" +"Троллинг, оскорбительные или уничижительные комментарии, а также личные " +"или политические нападки." +msgstr "" + +#: ../../root/code_of_conduct.rst:34 +msgid "Публичное или частное преследование." +msgstr "" + +#: ../../root/code_of_conduct.rst:35 +msgid "" +"Публикация личной информации других лиц, такой как физический или " +"электронный адрес, без их явного разрешения." +msgstr "" + +#: ../../root/code_of_conduct.rst:37 +msgid "" +"Иное поведение, которое можно обоснованно считать неуместным в " +"профессиональной среде." +msgstr "" + +#: ../../root/code_of_conduct.rst:43 +msgid "Наши обязанности" +msgstr "" + +#: ../../root/code_of_conduct.rst:45 +msgid "" +"Мейнтейнеры проекта несут ответственность за разъяснение и обеспечение " +"соблюдения наших стандартов приемлемого поведения и предпримут " +"соответствующие и справедливые корректирующие действия в ответ на любые " +"случаи неприемлемого поведения." +msgstr "" + +#: ../../root/code_of_conduct.rst:49 +msgid "" +"Мейнтейнеры проекта имеют право и обязанность удалять, редактировать или " +"отклонять комментарии, коммиты, код, правки в вики, задачи и другие " +"вклады, которые не соответствуют настоящему Кодексу поведения, или " +"временно либо навсегда заблокировать любого участника за другое " +"поведение, которое они сочтут неуместным, угрожающим, оскорбительным или " +"вредным." +msgstr "" + +#: ../../root/code_of_conduct.rst:58 +msgid "Сфера применения" +msgstr "" + +#: ../../root/code_of_conduct.rst:60 +msgid "" +"Настоящий Кодекс поведения применяется во всех пространствах сообщества, " +"а также когда человек официально представляет сообщество в публичных " +"местах. Примеры представления нашего сообщества включают использование " +"официального адреса электронной почты, публикации через официальный " +"аккаунт в социальных сетях или выступление в качестве назначенного " +"представителя на онлайн- или офлайн-мероприятии." +msgstr "" + +#: ../../root/code_of_conduct.rst:69 +msgid "Обеспечение соблюдения" +msgstr "" + +#: ../../root/code_of_conduct.rst:71 +msgid "" +"О случаях оскорбительного, преследовательского или иного неприемлемого " +"поведения можно сообщить руководителям сообщества, ответственным за " +"обеспечение правоприменения, по адресу . Все жалобы будут рассмотрены и " +"расследованы оперативно и справедливо." +msgstr "" + +#: ../../root/code_of_conduct.rst:75 +msgid "" +"Все руководители сообщества обязаны уважать частную жизнь и безопасность " +"заявителя любого инцидента." +msgstr "" + +#: ../../root/code_of_conduct.rst:81 +msgid "Атрибуция" +msgstr "" + +#: ../../root/code_of_conduct.rst:83 +msgid "" +"Настоящий Кодекс поведения адаптирован из `Contributor Covenant " +"`__, версии `1.4 `__ и `2.0 `__." +msgstr "" + diff --git a/docs/locales/en/LC_MESSAGES/root/contributing.po b/docs/locales/en/LC_MESSAGES/root/contributing.po index 21659f2..97607b9 100644 --- a/docs/locales/en/LC_MESSAGES/root/contributing.po +++ b/docs/locales/en/LC_MESSAGES/root/contributing.po @@ -8,7 +8,7 @@ msgid "" msgstr "" "Project-Id-Version: Argenta \n" "Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-10-15 16:09+0300\n" +"POT-Creation-Date: 2025-10-20 14:52+0300\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language: en\n" @@ -23,13 +23,635 @@ msgstr "" msgid "Вклад в проект" msgstr "Contributing" -#: ../../root/contributing.rst:6 +#: ../../root/contributing.rst:8 +msgid "Прежде всего, спасибо, что уделили время для внесения своего вклада! ❤️" +msgstr "" + +#: ../../root/contributing.rst:10 msgid "" -"``argenta`` открытый проект и мы рады новым разработчикам в нашем " -"сообществе." +"Мы приветствуем и ценим любые виды вклада. Пожалуйста, прочтите " +"соответствующий раздел, прежде чем делать свой вклад. Это значительно " +"облегчит работу для нас, мейнтейнеров, и сделает процесс более гладким " +"для всех участников. Сообщество с нетерпением ждет ваших вкладов. 🎉" msgstr "" -#: ../../root/contributing.rst:9 -msgid "Getting started" +#: ../../root/contributing.rst:14 +msgid "" +"Если вам нравится проект, но у вас просто нет времени на вклад, это " +"нормально. Есть и другие простые способы поддержать проект и выразить " +"свою признательность, которым мы также будем очень рады:" msgstr "" +#: ../../root/contributing.rst:16 +msgid "Поставить звезду проекту" +msgstr "" + +#: ../../root/contributing.rst:17 +msgid "Написать о нем в ``Twitter``" +msgstr "" + +#: ../../root/contributing.rst:18 +msgid "Ссылаться на этот проект в ``Readme`` вашего проекта" +msgstr "" + +#: ../../root/contributing.rst:19 +msgid "Упомянуть проект на местных встречах и рассказать о нем друзьям/коллегам" +msgstr "" + +#: ../../root/contributing.rst:24 +msgid "Содержание" +msgstr "" + +#: ../../root/contributing.rst:26 +msgid "`Кодекс поведения`_" +msgstr "" + +#: ../../root/contributing.rst:27 +msgid "`У меня есть вопрос`_" +msgstr "" + +#: ../../root/contributing.rst:28 +msgid "`Я хочу внести вклад`_" +msgstr "" + +#: ../../root/contributing.rst:29 +msgid "`Сообщение об ошибках`_" +msgstr "" + +#: ../../root/contributing.rst:30 +msgid "`Предложение улучшений`_" +msgstr "" + +#: ../../root/contributing.rst:31 +msgid "`Ваш первый вклад в код`_" +msgstr "" + +#: ../../root/contributing.rst:32 +msgid "`Улучшение документации`_" +msgstr "" + +#: ../../root/contributing.rst:33 +msgid "`Руководства по стилю`_" +msgstr "" + +#: ../../root/contributing.rst:34 +msgid "`Сообщения коммитов`_" +msgstr "" + +#: ../../root/contributing.rst:35 +msgid "`Присоединяйтесь к команде проекта`_" +msgstr "" + +#: ../../root/contributing.rst:40 +msgid "Кодекс поведения" +msgstr "" + +#: ../../root/contributing.rst:42 +msgid "" +"Этот проект и все его участники руководствуются :ref:`Кодексом поведения " +"Argenta `. Участвуя, вы обязуетесь соблюдать этот " +"кодекс. Пожалуйста, сообщайте о недопустимом поведении." +msgstr "" + +#: ../../root/contributing.rst:50 +msgid "У меня есть вопрос" +msgstr "" + +#: ../../root/contributing.rst:54 +msgid "" +"Если вы хотите задать вопрос, мы предполагаем, что вы уже ознакомились с " +"доступной `Документацией `_." +msgstr "" + +#: ../../root/contributing.rst:56 +msgid "" +"Прежде чем задать вопрос, лучше всего поискать существующие `Issues " +"`_, которые могут вам " +"помочь. Если вы нашли подходящий ``issue``, но все еще нуждаетесь в " +"разъяснениях, вы можете написать свой вопрос в этом ``issue``. Также " +"рекомендуется сначала поискать ответы в интернете." +msgstr "" + +#: ../../root/contributing.rst:58 +msgid "" +"Если после этого вы все еще чувствуете необходимость задать вопрос, мы " +"рекомендуем следующее:" +msgstr "" + +#: ../../root/contributing.rst:60 +msgid "Откройте новый `Issue `_." +msgstr "" + +#: ../../root/contributing.rst:61 +msgid "Предоставьте как можно больше контекста о том, с чем вы столкнулись." +msgstr "" + +#: ../../root/contributing.rst:62 +msgid "" +"Укажите версии проекта и платформы (cpython, pip и т.д.), в зависимости " +"от того, что кажется релевантным." +msgstr "" + +#: ../../root/contributing.rst:64 +msgid "Мы займемся вашей задачей как можно скорее." +msgstr "" + +#: ../../root/contributing.rst:71 +msgid "Я хочу внести вклад" +msgstr "" + +#: ../../root/contributing.rst:74 +msgid "Правовое уведомление" +msgstr "" + +#: ../../root/contributing.rst:77 +msgid "" +"Внося вклад в этот проект, вы должны согласиться с тем, что вы являетесь " +"автором 100% контента, что у вас есть необходимые права на этот контент, " +"и что предоставленный вами контент может распространяться под лицензией " +"проекта." +msgstr "" + +#: ../../root/contributing.rst:82 +msgid "Сообщение об ошибках" +msgstr "" + +#: ../../root/contributing.rst:85 +msgid "Перед отправкой отчета об ошибке" +msgstr "" + +#: ../../root/contributing.rst:86 +msgid "" +"Хороший отчет об ошибке не должен заставлять других вытягивать из вас " +"дополнительную информацию. Поэтому мы просим вас тщательно все изучить, " +"собрать информацию и подробно описать проблему в своем отчете. " +"Пожалуйста, выполните следующие шаги заранее, чтобы помочь нам исправить " +"любую потенциальную ошибку как можно быстрее." +msgstr "" + +#: ../../root/contributing.rst:88 ../../root/contributing.rst:129 +msgid "Убедитесь, что вы используете последнюю версию." +msgstr "" + +#: ../../root/contributing.rst:89 +msgid "" +"Определите, действительно ли ваша проблема является ошибкой, а не ошибкой" +" с вашей стороны, например, из-за использования несовместимых " +"компонентов/версий окружения (Убедитесь, что вы прочитали `документацию " +"`_. Если вам нужна поддержка, возможно, " +"стоит заглянуть в раздел `У меня есть вопрос`_)." +msgstr "" + +#: ../../root/contributing.rst:90 +msgid "" +"Чтобы увидеть, сталкивались ли другие пользователи (и, возможно, уже " +"решили) с той же проблемой, проверьте, нет ли уже отчета о вашей ошибке в" +" `трекере ошибок " +"`_." +msgstr "" + +#: ../../root/contributing.rst:91 +msgid "" +"Также обязательно поищите в интернете (включая ``Stack Overflow``), чтобы" +" узнать, обсуждали ли проблему пользователи за пределами сообщества " +"``GitHub``." +msgstr "" + +#: ../../root/contributing.rst:92 +msgid "Соберите информацию об ошибке:" +msgstr "" + +#: ../../root/contributing.rst:93 +msgid "Трассировка стека" +msgstr "" + +#: ../../root/contributing.rst:94 +msgid "ОС, платформа и версия ``Windows``, ``Linux``, ``macOS``, ``x86``, ``ARM``" +msgstr "" + +#: ../../root/contributing.rst:95 +msgid "" +"Версия интерпретатора, компилятора, SDK, среды выполнения, менеджера " +"пакетов, в зависимости от того, что кажется релевантным." +msgstr "" + +#: ../../root/contributing.rst:96 +msgid "Возможно, ваши входные данные и результат" +msgstr "" + +#: ../../root/contributing.rst:97 +msgid "" +"Можете ли вы надежно воспроизвести проблему? И можете ли вы воспроизвести" +" ее на старых версиях?" +msgstr "" + +#: ../../root/contributing.rst:100 +msgid "Как мне отправить хороший отчет об ошибке?" +msgstr "" + +#: ../../root/contributing.rst:103 +msgid "" +"Никогда не сообщайте о проблемах безопасности, уязвимостях или ошибках, " +"содержащих конфиденциальную информацию, в трекере задач или в других " +"публичных местах. Конфиденциальные ошибки должны быть отправлены по " +"электронной почте." +msgstr "" + +#: ../../root/contributing.rst:105 +msgid "" +"Мы используем ``Issues GitHub`` для отслеживания ошибок. Если вы " +"столкнулись с проблемой в проекте:" +msgstr "" + +#: ../../root/contributing.rst:107 +msgid "" +"Откройте `Issue `_. " +"(Поскольку на данном этапе мы не можем быть уверены, является ли это " +"ошибкой, мы просим вас пока не говорить об ошибке и не присваивать метку " +"задаче.)" +msgstr "" + +#: ../../root/contributing.rst:108 +msgid "Объясните поведение, которое вы ожидали, и фактическое поведение." +msgstr "" + +#: ../../root/contributing.rst:109 +msgid "" +"Пожалуйста, предоставьте как можно больше контекста и опишите *шаги для " +"воспроизведения*, чтобы кто-то другой мог воссоздать проблему " +"самостоятельно. Обычно это включает ваш код. Для хороших отчетов об " +"ошибках следует изолировать проблему и создать сокращенный тестовый " +"пример." +msgstr "" + +#: ../../root/contributing.rst:110 +msgid "Предоставьте информацию, которую вы собрали в предыдущем разделе." +msgstr "" + +#: ../../root/contributing.rst:112 +msgid "После того, как задача будет создана:" +msgstr "" + +#: ../../root/contributing.rst:114 +msgid "Команда проекта присвоит задаче соответствующую метку." +msgstr "" + +#: ../../root/contributing.rst:115 +msgid "" +"Член команды попытается воспроизвести проблему по вашим шагам. Если шагов" +" для воспроизведения нет или нет очевидного способа воспроизвести " +"проблему, команда попросит вас предоставить эти шаги и пометит задачу как" +" `needs-repro`. Ошибки с меткой `needs-repro` не будут рассматриваться до" +" тех пор, пока они не будут воспроизведены." +msgstr "" + +#: ../../root/contributing.rst:116 +msgid "" +"Если команда сможет воспроизвести проблему, она будет помечена как " +"`needs-fix`, а также, возможно, другими метками (например, `critical`), и" +" задача будет оставлена для :ref:`реализации кем-либо <Ваш первый вклад в" +" код>`." +msgstr "" + +#: ../../root/contributing.rst:123 +msgid "Предложение улучшений" +msgstr "" + +#: ../../root/contributing.rst:125 +msgid "" +"Этот раздел поможет вам отправить предложение по улучшению ``Argenta``, " +"**включая совершенно новые функции и незначительные улучшения " +"существующей функциональности**. Следование этим рекомендациям поможет " +"мейнтейнерам и сообществу понять ваше предложение и найти связанные с ним" +" предложения." +msgstr "" + +#: ../../root/contributing.rst:128 +msgid "Перед отправкой предложения по улучшению" +msgstr "" + +#: ../../root/contributing.rst:130 +msgid "" +"Внимательно прочтите `документацию `_ и " +"выясните, не реализована ли уже данная функциональность, возможно, через " +"индивидуальную конфигурацию." +msgstr "" + +#: ../../root/contributing.rst:131 +msgid "" +"Выполните `поиск `_, чтобы " +"проверить, не было ли уже предложено данное улучшение. Если да, добавьте " +"комментарий к существующей задаче вместо создания новой." +msgstr "" + +#: ../../root/contributing.rst:132 +msgid "" +"Определите, соответствует ли ваша идея масштабам и целям проекта. Вам " +"предстоит убедительно доказать разработчикам проекта достоинства этой " +"функции. Помните, что мы хотим видеть функции, которые будут полезны " +"большинству наших пользователей, а не только небольшой их части. Если вы " +"ориентируетесь только на меньшинство пользователей, рассмотрите " +"возможность написания дополнения/плагина." +msgstr "" + +#: ../../root/contributing.rst:135 +msgid "Как мне отправить хорошее предложение по улучшению?" +msgstr "" + +#: ../../root/contributing.rst:136 +msgid "" +"Предложения по улучшению отслеживаются как `Issues GitHub " +"`_." +msgstr "" + +#: ../../root/contributing.rst:138 +msgid "" +"Используйте **четкий и описательный заголовок** для задачи, чтобы " +"идентифицировать предложение." +msgstr "" + +#: ../../root/contributing.rst:139 +msgid "" +"Предоставьте **пошаговое описание предлагаемого улучшения** как можно " +"подробнее." +msgstr "" + +#: ../../root/contributing.rst:140 +msgid "" +"**Опишите текущее поведение** и **объясните, какое поведение вы ожидали " +"увидеть вместо этого** и почему. На этом этапе вы также можете указать, " +"какие альтернативы вам не подходят." +msgstr "" + +#: ../../root/contributing.rst:141 +msgid "" +"Вы можете **включить скриншоты или записи экрана**, которые помогут " +"продемонстрировать шаги или указать на часть, к которой относится " +"предложение." +msgstr "" + +#: ../../root/contributing.rst:142 +msgid "" +"**Объясните, почему это улучшение было бы полезно** большинству " +"пользователей ``Argenta``. Вы также можете указать на другие проекты, " +"которые решили эту проблему лучше и которые могут послужить источником " +"вдохновения." +msgstr "" + +#: ../../root/contributing.rst:149 +msgid "Ваш первый вклад в код" +msgstr "" + +#: ../../root/contributing.rst:151 +msgid "" +"Не знаете, с чего начать свой вклад в ``Argenta``? Вы можете начать с " +"просмотра задач с метками ``good first issue`` и ``help wanted`` в нашем " +"репозитории на ``GitHub``. Это задачи, которые хорошо подходят для " +"новичков." +msgstr "" + +#: ../../root/contributing.rst:153 +msgid "" +"Чтобы начать вносить свой первый вклад в код, пожалуйста, выполните " +"следующие шаги для настройки вашего локального окружения для разработки." +msgstr "" + +#: ../../root/contributing.rst:155 +msgid "Сделайте форк репозитория ``Argenta`` на ``GitHub``." +msgstr "" + +#: ../../root/contributing.rst:156 +msgid "Клонируйте ваш форк на локальную машину:" +msgstr "" + +#: ../../root/contributing.rst:163 +msgid "Создайте и активируйте виртуальное окружение." +msgstr "" + +#: ../../root/contributing.rst:175 +msgid "Установите зависимости проекта, включая инструменты для разработки." +msgstr "" + +#: ../../root/contributing.rst:181 +msgid "" +"Создайте новую ветку для вашей новой функции или исправления ошибки. " +"Используйте описательное имя, например ``fix/login-bug`` или ``feat/new-" +"widget``." +msgstr "" + +#: ../../root/contributing.rst:187 +msgid "" +"Внесите свои изменения! Напишите код и не забудьте добавить или обновить " +"тесты для ваших изменений." +msgstr "" + +#: ../../root/contributing.rst:188 +msgid "Запустите тесты, чтобы убедиться, что все работает корректно." +msgstr "" + +#: ../../root/contributing.rst:194 +msgid "" +"Сделайте коммит ваших изменений, следуя нашему руководству по стилю " +"сообщений коммитов, и отправьте их в ваш форк." +msgstr "" + +#: ../../root/contributing.rst:202 +msgid "" +"Откройте ``Pull Request`` из вашей ветки в ветку ``main`` официального " +"репозитория ``Argenta``. Предоставьте четкое описание проблемы и вашего " +"решения. Укажите номер связанной задачи, если это применимо." +msgstr "" + +#: ../../root/contributing.rst:209 +msgid "Улучшение документации" +msgstr "" + +#: ../../root/contributing.rst:211 +msgid "" +"Хорошая документация крайне важна для любого проекта. Мы используем " +"``Sphinx`` для генерации нашей документации из исходных файлов, " +"расположенных в директории ``docs/``. Мы приветствуем любые улучшения, от" +" исправления простой опечатки до написания целого нового раздела." +msgstr "" + +#: ../../root/contributing.rst:215 +msgid "Мы поддерживаем документацию на двух языках: русском и английском." +msgstr "" + +#: ../../root/contributing.rst:217 +msgid "" +"Для улучшения документации вы можете следовать процессу, похожему на " +"внесение вклада в код:" +msgstr "" + +#: ../../root/contributing.rst:219 +msgid "" +"Убедитесь, что ваше окружение для разработки настроено, как описано в " +"разделе `Ваш первый вклад в код`_." +msgstr "" + +#: ../../root/contributing.rst:220 +msgid "Перейдите в директорию с документацией." +msgstr "" + +#: ../../root/contributing.rst:226 +msgid "" +"Внесите необходимые изменения в **русскую** версию документации - " +"``docs/index.rst`` и/или ``docs/root/*``" +msgstr "" + +#: ../../root/contributing.rst:227 +msgid "Чтобы собрать документацию локально и увидеть ваши изменения, выполните:" +msgstr "" + +#: ../../root/contributing.rst:233 +msgid "" +"Откройте ``127.0.0.1:8000`` в вашем веб-браузере, чтобы просмотреть " +"сгенерированную документацию." +msgstr "" + +#: ../../root/contributing.rst:234 +msgid "" +"После завершения работы над русской документацией необходимо создать " +"английский перевод:" +msgstr "" + +#: ../../root/contributing.rst:240 +msgid "" +"После обновления шаблона перевода, обновите необходимые файлы перевода, " +"расположенные по пути ``docs/locales/en/LC_MESSAGES``." +msgstr "" + +#: ../../root/contributing.rst:241 +msgid "" +"Когда вы будете довольны своими изменениями, сделайте коммит и откройте " +"``Pull Request``. Используйте префикс ``docs:`` в сообщении коммита." +msgstr "" + +#: ../../root/contributing.rst:248 +msgid "Руководства по стилю" +msgstr "" + +#: ../../root/contributing.rst:253 +msgid "Сообщения коммитов" +msgstr "" + +#: ../../root/contributing.rst:255 +msgid "" +"Мы следуем спецификации `Conventional Commits " +"`_ для наших сообщений " +"коммитов. Это приводит к более читаемым сообщениям, которые легко " +"отслеживать при просмотре истории проекта, и позволяет автоматически " +"генерировать журнал изменений." +msgstr "" + +#: ../../root/contributing.rst:257 +msgid "" +"Каждое сообщение коммита состоит из **заголовка**, **тела** и **нижнего " +"колонтитула**." +msgstr "" + +#: ../../root/contributing.rst:267 +msgid "``<тип>`` должен быть одним из следующих:" +msgstr "" + +#: ../../root/contributing.rst:269 +msgid "**feat**: Новая функция для пользователя." +msgstr "" + +#: ../../root/contributing.rst:270 +msgid "**fix**: Исправление ошибки для пользователя." +msgstr "" + +#: ../../root/contributing.rst:271 +msgid "**docs**: Только изменения в документации." +msgstr "" + +#: ../../root/contributing.rst:272 +msgid "" +"**style**: Изменения, не влияющие на смысл кода (пробелы, форматирование " +"и т.д.)." +msgstr "" + +#: ../../root/contributing.rst:273 +msgid "" +"**refactor**: Изменение кода, которое не исправляет ошибку и не добавляет" +" новую функцию." +msgstr "" + +#: ../../root/contributing.rst:274 +msgid "**perf**: Изменение кода, улучшающее производительность." +msgstr "" + +#: ../../root/contributing.rst:275 +msgid "**test**: Добавление недостающих тестов или исправление существующих." +msgstr "" + +#: ../../root/contributing.rst:276 +msgid "" +"**chore**: Изменения в процессе сборки или вспомогательных инструментах и" +" библиотеках." +msgstr "" + +#: ../../root/contributing.rst:279 +msgid "Примеры" +msgstr "" + +#: ../../root/contributing.rst:280 +msgid "Простое исправление: ``fix: correct typo in user authentication flow``" +msgstr "" + +#: ../../root/contributing.rst:283 +msgid "" +"Новая функция с областью видимости: ``feat(api): add new endpoint for " +"user profiles``" +msgstr "" + +#: ../../root/contributing.rst:291 +msgid "Присоединяйтесь к команде проекта" +msgstr "" + +#: ../../root/contributing.rst:293 +msgid "" +"Мы всегда ищем энтузиастов и преданных своему делу людей для " +"присоединения к нашей команде проекта. Если вы являетесь постоянным " +"участником и продемонстрировали глубокое понимание целей и архитектуры " +"проекта, вы можете стать хорошим кандидатом на роль мейнтейнера." +msgstr "" + +#: ../../root/contributing.rst:295 +msgid "" +"Активные члены сообщества могут стать членами команды. Обычно это " +"включает в себя:" +msgstr "" + +#: ../../root/contributing.rst:297 +msgid "Постоянный вклад в виде высококачественного кода и документации." +msgstr "" + +#: ../../root/contributing.rst:298 +msgid "Помощь другим пользователям, отвечая на вопросы и разбирая проблемы." +msgstr "" + +#: ../../root/contributing.rst:299 +msgid "" +"Проверку ``Pull Request`` от других участников с конструктивной обратной " +"связью." +msgstr "" + +#: ../../root/contributing.rst:301 +msgid "" +"Если вы заинтересованы в том, чтобы стать постоянным членом команды, " +"лучший способ начать — это быть активным и полезным членом сообщества. " +"Существующие мейнтейнеры заметят ваши усилия и могут связаться с вами с " +"приглашением присоединиться к команде." +msgstr "" + +#~ msgid "" +#~ "``argenta`` открытый проект и мы рады" +#~ " новым разработчикам в нашем сообществе." +#~ msgstr "" + +#~ msgid "Getting started" +#~ msgstr "" + diff --git a/docs/locales/en/LC_MESSAGES/root/dependency_injection.po b/docs/locales/en/LC_MESSAGES/root/dependency_injection.po index d0c44b4..7e7844e 100644 --- a/docs/locales/en/LC_MESSAGES/root/dependency_injection.po +++ b/docs/locales/en/LC_MESSAGES/root/dependency_injection.po @@ -8,7 +8,7 @@ msgid "" msgstr "" "Project-Id-Version: Argenta \n" "Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-10-16 17:03+0300\n" +"POT-Creation-Date: 2025-10-20 14:52+0300\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language: en\n" @@ -24,6 +24,108 @@ msgid "Внедрение зависимостей" msgstr "Dependency Injection" #: ../../root/dependency_injection.rst:6 -msgid "мда мда мда" +msgid "" +"Внедрение зависимостей (Dependency Injection, DI) — это паттерн " +"проектирования, который помогает писать слабосвязанный, легко тестируемый" +" и расширяемый код. Вместо того чтобы хендлеры сами создавали нужные им " +"объекты (зависимости) они лишь объявляют о необходимости в их получении, " +"а ``Argenta`` \"внедряет\" их в хендлеры в момент вызова." msgstr "" +#: ../../root/dependency_injection.rst:8 +msgid "" +"``Argenta`` использует популярную библиотеку ``dishka`` для реализации " +"DI, что позволяет вам декларативно объявлять зависимости прямо в " +"сигнатурах ваших хендлеров. Более подробно про ``DI``, ``IoC``, ``API`` " +"создания провайдеров и другое вы можете прочитать тут_." +msgstr "" + +#: ../../root/dependency_injection.rst:14 +msgid "Основная идея" +msgstr "" + +#: ../../root/dependency_injection.rst:16 +msgid "" +"Представьте, что вашему хендлеру для работы нужен доступ к базе данных. " +"Вместо того чтобы импортировать и инициализировать соединение внутри " +"функции, вы просто объявляете его как аргумент с тайп-хинтом:" +msgstr "" + +#: ../../root/dependency_injection.rst:19 +msgid "" +"``argenta.di.FromDishka`` это алиас к ``dishka.FromDishka``, они " +"полностью взаимозаменяемы." +msgstr "" + +#: ../../root/dependency_injection.rst:24 +msgid "" +"``Argenta`` -> ``dishka`` зарезолвит тайпхинты и внедрит зависимость с " +"возвращаемым типом ``Connection``, прежде чем использовать зависимость её" +" нужно создать, для этого нужно создать соответствующий провайдер." +msgstr "" + +#: ../../root/dependency_injection.rst:29 +msgid "После создания провайдера, его нужно зарегистрировать в оркестраторе." +msgstr "" + +#: ../../root/dependency_injection.rst:35 +msgid "Как это работает?" +msgstr "" + +#: ../../root/dependency_injection.rst:37 +msgid "В основе DI в Argente лежат **провайдеры** и **контейнер**." +msgstr "" + +#: ../../root/dependency_injection.rst:39 +msgid "" +"**Провайдер (Provider)** — это \"рецепт\", который объясняет, как " +"создавать и настраивать ту или иную зависимость (например, подключение к " +"БД, API-клиент или любой другой сервис)." +msgstr "" + +#: ../../root/dependency_injection.rst:40 +msgid "" +"**Контейнер (IoC Container)** — это \"фабрика\", которая хранит все " +"рецепты (провайдеры) и по запросу создаёт и выдаёт готовые зависимости." +msgstr "" + +#: ../../root/dependency_injection.rst:43 +msgid "Встроенные провайдеры" +msgstr "" + +#: ../../root/dependency_injection.rst:45 +msgid "" +"``Argenta`` поставляется с предопределённым провайдером, который даёт " +"доступ к важным системным зависимостям без какой-либо настройки. К " +"примеру вы можете получить объект ``ArgSpace``, который представляет из " +"себя распаршенные аргументы командной строки при запуске приложения." +msgstr "" + +#: ../../root/dependency_injection.rst:47 +msgid "" +"Краткий сэмпл кода, который получает объект ``ArgSpace`` и выводит в " +"консоль аргумент с именем \"type\":" +msgstr "" + +#: ../../root/dependency_injection.rst:53 +msgid "Обмен данными между хендлерами" +msgstr "" + +#: ../../root/dependency_injection.rst:55 +msgid "" +"Помимо DI, хендлеры могут общаться друг с другом в контексте приложения " +"через **объект контекста** (в ``Argenta`` эту роль выполняет объект " +"``Response``)." +msgstr "" + +#: ../../root/dependency_injection.rst:57 +msgid "Каждый хендлер может записывать данные, читать, обновлять и удалять." +msgstr "" + +#: ../../root/dependency_injection.rst:61 +msgid "Подробнее об этом можно прочитать в разделе :ref:`root_api_response`." +msgstr "" + +#~ msgid "мда мда мда" +#~ msgstr "" + diff --git a/docs/locales/en/LC_MESSAGES/root/error_handling.po b/docs/locales/en/LC_MESSAGES/root/error_handling.po index 9245b5c..535ddd5 100644 --- a/docs/locales/en/LC_MESSAGES/root/error_handling.po +++ b/docs/locales/en/LC_MESSAGES/root/error_handling.po @@ -8,7 +8,7 @@ msgid "" msgstr "" "Project-Id-Version: Argenta \n" "Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-10-17 18:46+0300\n" +"POT-Creation-Date: 2025-10-20 14:52+0300\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language: en\n" @@ -19,15 +19,16 @@ msgstr "" "Content-Transfer-Encoding: 8bit\n" "Generated-By: Babel 2.17.0\n" -#: ../../root/error_handling.rst:2 -msgid "Обработка ошибок" +#: ../../root/error_handling.rst:4 +#, fuzzy +msgid "Стандартная обработка ошибок" msgstr "Errors handling" -#: ../../root/error_handling.rst:5 -msgid "Конфигурация" +#: ../../root/error_handling.rst:7 +msgid "О разделе" msgstr "" -#: ../../root/error_handling.rst:7 +#: ../../root/error_handling.rst:9 msgid "" "``Argenta`` в рантайме вызывает исключения в пограничных случаях " "пользовательского ввода. Все исключения обрабатываются системными " @@ -38,38 +39,39 @@ msgid "" ":ref:`ниже `" msgstr "" -#: ../../root/error_handling.rst:13 +#: ../../root/error_handling.rst:15 msgid "" "Все исключения никогда не остаются необработанными, так как у них есть " "стандартные хэндлеры. Поэтому переопределение опционально." msgstr "" -#: ../../root/error_handling.rst:15 +#: ../../root/error_handling.rst:17 msgid "Краткий сэмпл кода, переопределяющего хэндлер ввода пустой команды" msgstr "" -#: ../../root/error_handling.rst:25 +#: ../../root/error_handling.rst:27 msgid "Возможные исключения и нестандартное поведение" msgstr "" -#: ../../root/error_handling.rst:28 +#: ../../root/error_handling.rst:30 msgid "``UnprocessedInputFlagException``: Необрабатываемый ввод от пользователя" msgstr "" -#: ../../root/error_handling.rst:30 +#: ../../root/error_handling.rst:32 msgid "" "Исключение вызывается, когда пользователь вводит команду с некорректным " -"синтаксисом и парсер не может *распарсить* её. В большинстве случаев это " -"означат, что проблема в синтаксисе введённых флагов команды, подробнее о " -"флагах и их синтаксисе в :ref:`Flags `." +"синтаксисом и как следствие парсер не может *распарсить* её. В " +"большинстве случаев это означат, что проблема в синтаксисе введённых " +"флагов команды, подробнее о флагах и их синтаксисе в :ref:`Flags " +"`." msgstr "" -#: ../../root/error_handling.rst:34 ../../root/error_handling.rst:57 -#: ../../root/error_handling.rst:79 ../../root/error_handling.rst:102 +#: ../../root/error_handling.rst:36 ../../root/error_handling.rst:62 +#: ../../root/error_handling.rst:84 ../../root/error_handling.rst:107 msgid "Дефолтный хэндлер выводит в консоль" msgstr "" -#: ../../root/error_handling.rst:40 +#: ../../root/error_handling.rst:42 msgid "" "Для переопределения стандартного поведения используется сеттер " "``.set_incorrect_input_syntax_handler(_: " @@ -81,25 +83,31 @@ msgid "" "возвращает." msgstr "" -#: ../../root/error_handling.rst:44 +#: ../../root/error_handling.rst:46 msgid "" "Сэмпл кода, переопределяющего хэндлер ввода команды с некорректным " "синтаксисом:" msgstr "" -#: ../../root/error_handling.rst:52 +#: ../../root/error_handling.rst:54 msgid "``RepeatedInputFlagsException``: Повторяющийся флаг в введённой команде" msgstr "" -#: ../../root/error_handling.rst:54 +#: ../../root/error_handling.rst:56 msgid "" "Исключение вызывается, когда пользователь вводит команду с повторяющимся " -"флагом, флаг(:ref:`InputFlag `) считается повторяющимся, если" -" введён флаг с таким же именем, именно именем, без префикса. Подробнее о " -"флагах и их синтаксисе в :ref:`Flags `." +"флагом, пара введённых флагов(:ref:`InputFlag " +"`) считается равной, если у них одинаковые " +"имена. Подробнее о флагах и их синтаксисе в :ref:`Flags `." msgstr "" -#: ../../root/error_handling.rst:63 +#: ../../root/error_handling.rst:60 +msgid "" +"Сравнение на равенство у регистрируемых флагов(Flag) происходит иначе, " +"подробнее в :ref:`Flag `." +msgstr "" + +#: ../../root/error_handling.rst:68 msgid "" "Для переопределения стандартного поведения используется сеттер " "``.set_repeated_input_flags_handler(_: " @@ -111,23 +119,23 @@ msgid "" "возвращает." msgstr "" -#: ../../root/error_handling.rst:67 +#: ../../root/error_handling.rst:72 msgid "" "Сэмпл кода, переопределяющего хэндлер ввода команды с повторяющимися " "флагами:" msgstr "" -#: ../../root/error_handling.rst:75 +#: ../../root/error_handling.rst:80 msgid "``EmptyInputCommandException``: Введена пустая команда" msgstr "" -#: ../../root/error_handling.rst:77 +#: ../../root/error_handling.rst:82 msgid "" "Исключение вызывается, когда пользователь вводит команду в виде строки из" " пробельных символов - ``\\n``, ``\\t``, пробел и т.д." msgstr "" -#: ../../root/error_handling.rst:85 +#: ../../root/error_handling.rst:90 msgid "" "Для переопределения стандартного поведения используется сеттер " "``.set_empty_command_handler(_: EmptyCommandHandler)``, протокол " @@ -136,22 +144,22 @@ msgid "" "которая не принимает аргументов и ничего не возвращает." msgstr "" -#: ../../root/error_handling.rst:89 +#: ../../root/error_handling.rst:94 msgid "Сэмпл кода, переопределяющего хэндлер ввода пустой команды:" msgstr "" -#: ../../root/error_handling.rst:97 +#: ../../root/error_handling.rst:102 msgid "``Поведение обработки неизвестной команды``: Введена неизвестная команда" msgstr "" -#: ../../root/error_handling.rst:99 +#: ../../root/error_handling.rst:104 msgid "" "Поведение триггерится, когда пользователь вводит команду, которая не " "зарегистрирована ни в одном роутере и не является алиасом ни для одной " "зарегистрированной команды." msgstr "" -#: ../../root/error_handling.rst:108 +#: ../../root/error_handling.rst:113 msgid "" "Для переопределения стандартного поведения используется сеттер " "``.set_unknown_command_handler(_: " @@ -163,35 +171,35 @@ msgid "" "не возвращает." msgstr "" -#: ../../root/error_handling.rst:112 +#: ../../root/error_handling.rst:117 msgid "Сэмпл кода, переопределяющего хэндлер ввода неизвестной команды:" msgstr "" -#: ../../root/error_handling.rst:120 +#: ../../root/error_handling.rst:125 msgid "``Поведение выхода из приложения``: Введена команда выхода" msgstr "" -#: ../../root/error_handling.rst:122 +#: ../../root/error_handling.rst:127 msgid "" "Поведение триггерится, когда пользователь вводит команду, которая " "маркирована как команда завершения работы." msgstr "" -#: ../../root/error_handling.rst:124 +#: ../../root/error_handling.rst:129 msgid "Дефолтный хэндлер выводит в консоль текст и завершает работу приложения." msgstr "" -#: ../../root/error_handling.rst:130 +#: ../../root/error_handling.rst:135 msgid "" "Для переопределения стандартного поведения используется сеттер " "``.set_exit_command_handler(_: NonStandardBehaviorHandler[Response])``, " "протокол ``NonStandardBehaviorHandler[Response]`` соответствует " "``Callable[[Response], None]``, то есть хэндлер должен быть вызываемым " "объектом, к примеру функция или лямбда, которая принимает обязательный " -"аргумент типа :ref:`Response ` и ничего не возвращает." +"аргумент типа :ref:`Response ` и ничего не возвращает." msgstr "" -#: ../../root/error_handling.rst:134 +#: ../../root/error_handling.rst:139 msgid "Сэмпл кода, переопределяющего хэндлер ввода команды выхода:" msgstr "" @@ -421,3 +429,39 @@ msgstr "" #~ "зарегистрированной команды." #~ msgstr "" +#~ msgid "Конфигурация" +#~ msgstr "" + +#~ msgid "" +#~ "Исключение вызывается, когда пользователь " +#~ "вводит команду с некорректным синтаксисом " +#~ "и парсер не может *распарсить* её. " +#~ "В большинстве случаев это означат, что" +#~ " проблема в синтаксисе введённых флагов " +#~ "команды, подробнее о флагах и их " +#~ "синтаксисе в :ref:`Flags `." +#~ msgstr "" + +#~ msgid "" +#~ "Исключение вызывается, когда пользователь " +#~ "вводит команду с повторяющимся флагом, " +#~ "флаг(:ref:`InputFlag `) считается " +#~ "повторяющимся, если введён флаг с таким" +#~ " же именем, именно именем, без " +#~ "префикса. Подробнее о флагах и их " +#~ "синтаксисе в :ref:`Flags `." +#~ msgstr "" + +#~ msgid "" +#~ "Для переопределения стандартного поведения " +#~ "используется сеттер ``.set_exit_command_handler(_: " +#~ "NonStandardBehaviorHandler[Response])``, протокол " +#~ "``NonStandardBehaviorHandler[Response]`` соответствует " +#~ "``Callable[[Response], None]``, то есть " +#~ "хэндлер должен быть вызываемым объектом, " +#~ "к примеру функция или лямбда, которая" +#~ " принимает обязательный аргумент типа " +#~ ":ref:`Response ` и ничего не " +#~ "возвращает." +#~ msgstr "" + diff --git a/docs/locales/en/LC_MESSAGES/root/flags.po b/docs/locales/en/LC_MESSAGES/root/flags.po index 984d9cd..8b4478a 100644 --- a/docs/locales/en/LC_MESSAGES/root/flags.po +++ b/docs/locales/en/LC_MESSAGES/root/flags.po @@ -8,7 +8,7 @@ msgid "" msgstr "" "Project-Id-Version: Argenta \n" "Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-10-16 17:03+0300\n" +"POT-Creation-Date: 2025-10-20 14:52+0300\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language: en\n" @@ -19,7 +19,99 @@ msgstr "" "Content-Transfer-Encoding: 8bit\n" "Generated-By: Babel 2.17.0\n" -#: ../../root/flags.rst:2 -msgid "Флаги" +#: ../../root/flags.rst:4 +msgid "Флаги вводимых команд" msgstr "" +#: ../../root/flags.rst:6 +msgid "" +"Флаги (или параметры) — это специальные аргументы, которые конечный юзер " +"может добавлять к командам, чтобы управлять их поведением." +msgstr "" + +#: ../../root/flags.rst:9 +msgid "Синтаксис флагов" +msgstr "" + +#: ../../root/flags.rst:11 +msgid "Обобщённый синтаксис выглядит так:" +msgstr "" + +#: ../../root/flags.rst:17 +msgid "" +"То есть, у флага обязательно должен быть префикс, который может быть " +"одним, двум или трем минусам. После префикса следует имя флага, без " +"пробела, после, через пробел, идёт значение флага, если оно есть." +msgstr "" + +#: ../../root/flags.rst:21 +msgid "Два типа флагов" +msgstr "" + +#: ../../root/flags.rst:23 +msgid "" +"Флаги бывают двух основных видов: без значений (переключатели) и со " +"значениями. ``Argenta`` позволяет регистрировать и вводить флаги обоих " +"типов в любой последовательности для одной команды." +msgstr "" + +#: ../../root/flags.rst:26 +msgid "" +"Ошибки валидации значений являются пассивными, их не нужно обрабатывать " +"явно. У каждого инстанса :ref:`InputFlag ` " +"есть поле ``status``, по которому можно определить результат валидации " +"флага. **Конкретная реализация и описание API вы можете найти в разделе**" +" :ref:`Flag `." +msgstr "" + +#: ../../root/flags.rst:28 +msgid "" +"При регистрации флага вы можете указать допустимые для него значения, по " +"умолчанию любое введённое значение для флага будет валидным. Допустимые " +"значения можно указать различными способами:" +msgstr "" + +#: ../../root/flags.rst:31 +msgid "Ограничение по списку возможных значений" +msgstr "" + +#: ../../root/flags.rst:33 +msgid "Вы можете заранее определить список допустимых значений для флага." +msgstr "" + +#: ../../root/flags.rst:35 ../../root/flags.rst:52 +msgid "**Пример:**" +msgstr "" + +#: ../../root/flags.rst:37 +msgid "" +"Предположим, у вас есть флаг ``--format``, который может принимать только" +" значения ``json`` или ``xml``." +msgstr "" + +#: ../../root/flags.rst:48 +msgid "Проверка с помощью регулярных выражений" +msgstr "" + +#: ../../root/flags.rst:50 +msgid "" +"Для более сложных проверок вы можете использовать регулярные выражения. " +"Это особенно полезно, когда значение должно соответствовать определённому" +" формату, например, быть email-адресом, датой или номером телефона." +msgstr "" + +#: ../../root/flags.rst:54 +msgid "" +"Допустим, флаг ``--email`` должен принимать только корректные " +"email-адреса." +msgstr "" + +#: ../../root/flags.rst:64 +msgid "" +"Встроенная валидация избавляет вас от необходимости писать ручные " +"проверки и делает ваш код более декларативным." +msgstr "" + +#~ msgid "Флаги" +#~ msgstr "" + diff --git a/docs/locales/en/LC_MESSAGES/root/overriding_formatting.po b/docs/locales/en/LC_MESSAGES/root/overriding_formatting.po index 0f4e0e2..7096b6b 100644 --- a/docs/locales/en/LC_MESSAGES/root/overriding_formatting.po +++ b/docs/locales/en/LC_MESSAGES/root/overriding_formatting.po @@ -8,7 +8,7 @@ msgid "" msgstr "" "Project-Id-Version: Argenta \n" "Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-10-16 17:03+0300\n" +"POT-Creation-Date: 2025-10-20 14:52+0300\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language: en\n" @@ -20,10 +20,95 @@ msgstr "" "Generated-By: Babel 2.17.0\n" #: ../../root/overriding_formatting.rst:4 -msgid "Переопределение форматирования" +#, fuzzy +msgid "Стандартное форматирование" msgstr "Overriding formatting" #: ../../root/overriding_formatting.rst:6 -msgid "ндааааааааааааааа" +msgid "" +"По умолчанию в ``Argenta`` используется библиотека ``rich`` для вывода " +"текста с расширенным форматированием в консоли. ``rich`` позволяет " +"применять цвета, стили (жирный, курсив, подчеркнутый), составлять " +"таблицы, выделять синтаксис кода и многое другое, что значительно " +"улучшает визуальное восприятие текста." msgstr "" +#: ../../root/overriding_formatting.rst:8 +msgid "" +"Вывод системных сообщений производится с помощью метода ``print`` объекта" +" ``Console`` из библиотеки ``rich``, который обладает интерфейсом, " +"совместимым со встроенной функцией ``print``." +msgstr "" + +#: ../../root/overriding_formatting.rst:13 +#, fuzzy +msgid "Управление стандартным форматированием" +msgstr "Overriding formatting" + +#: ../../root/overriding_formatting.rst:15 +msgid "" +"При создании экземпляра класса ``App`` предусмотрен параметр " +"``override_system_messages`` типа ``bool`` (по умолчанию ``False``), " +"который позволяет включать или отключать стандартное форматирование " +"системных сообщений." +msgstr "" + +#: ../../root/overriding_formatting.rst:17 +msgid "" +"Если установить этот флаг в ``True``, стандартное форматирование, " +"применяемое по умолчанию (например, стилизация текста и ASCII-арт), будет" +" отключено, и системные сообщения будут выводиться в \"сыром\" виде, без " +"дополнительных стилей." +msgstr "" + +#: ../../root/overriding_formatting.rst:22 +msgid "Приветственное и прощальное сообщения" +msgstr "" + +#: ../../root/overriding_formatting.rst:24 +msgid "" +"Приветственное (``initial_message``) и прощальное (``farewell_message``) " +"сообщения по умолчанию формируются как ASCII-графика с помощью библиотеки" +" ``art``. В частности, используется функция ``text2art``, которая " +"преобразует обычный текст в стилизованное ASCII-арт изображение." +msgstr "" + +#: ../../root/overriding_formatting.rst:27 +msgid "" +"Библиотека ``art`` ориентирована на работу с ASCII-символами и **не " +"поддерживает корректный вывод кириллицы**. Это приводит к искажению или " +"некорректному отображению символов русского и других кириллических " +"алфавитов. Если ваше приветственное сообщение содержит кириллицу, " +"рекомендуется отключить стандартное форматирование с помощью " +"``override_system_messages=True`` или использовать только латинские " +"символы." +msgstr "" + +#: ../../root/overriding_formatting.rst:32 +msgid "Кастомизация вывода" +msgstr "" + +#: ../../root/overriding_formatting.rst:34 +msgid "" +"Для полной замены логики вывода сообщений в конструкторе ``App`` доступен" +" параметр ``print_func``." +msgstr "" + +#: ../../root/overriding_formatting.rst:36 +msgid "" +"**print_func**: ``Printer`` - Протокол ``Printer`` соответствует " +"``Callable[[str], None]``. Этот параметр позволяет передать любую " +"вызываемую сущность (например, функцию или лямбду), которая будет " +"использоваться для вывода всех системных сообщений. По умолчанию это " +"обертка вокруг ``rich.console.Console().print``. Вы можете передать сюда " +"свою функцию, чтобы, например, логировать вывод в файл или отправлять его" +" по сети." +msgstr "" + +#: ../../root/overriding_formatting.rst:40 +msgid "Пример использования" +msgstr "" + +#~ msgid "ндааааааааааааааа" +#~ msgstr "" + diff --git a/docs/locales/en/LC_MESSAGES/root/quickstart.po b/docs/locales/en/LC_MESSAGES/root/quickstart.po index 080ff52..1f3dfa8 100644 --- a/docs/locales/en/LC_MESSAGES/root/quickstart.po +++ b/docs/locales/en/LC_MESSAGES/root/quickstart.po @@ -8,7 +8,7 @@ msgid "" msgstr "" "Project-Id-Version: Argenta \n" "Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-10-15 16:23+0300\n" +"POT-Creation-Date: 2025-10-20 14:52+0300\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language: en\n" @@ -32,7 +32,7 @@ msgid "" "**Определение роутера и хэндлеров**. За регистрацию функции как " "обработчика отвечает декоратор ``@router.command``, хэндлер всегда должен" " принимать аргумент с типом ``Response``, подробнее в :ref:`разделе " -"`." +"`." msgstr "" #: ../../root/quickstart.rst:17 @@ -74,3 +74,12 @@ msgstr "" #~ msgid "**Запуск приложения**, запускаем приложение как обычный процесс." #~ msgstr "" +#~ msgid "" +#~ "**Определение роутера и хэндлеров**. За " +#~ "регистрацию функции как обработчика отвечает" +#~ " декоратор ``@router.command``, хэндлер всегда" +#~ " должен принимать аргумент с типом " +#~ "``Response``, подробнее в :ref:`разделе " +#~ "`." +#~ msgstr "" + diff --git a/docs/locales/en/LC_MESSAGES/root/redirect_stdout.po b/docs/locales/en/LC_MESSAGES/root/redirect_stdout.po index df11515..61f1aff 100644 --- a/docs/locales/en/LC_MESSAGES/root/redirect_stdout.po +++ b/docs/locales/en/LC_MESSAGES/root/redirect_stdout.po @@ -8,7 +8,7 @@ msgid "" msgstr "" "Project-Id-Version: Argenta \n" "Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-10-15 16:09+0300\n" +"POT-Creation-Date: 2025-10-20 14:52+0300\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language: en\n" @@ -19,7 +19,200 @@ msgstr "" "Content-Transfer-Encoding: 8bit\n" "Generated-By: Babel 2.17.0\n" -#: ../../root/redirect_stdout.rst:2 -msgid "Перенаправление стандартного вывода" +#: ../../root/redirect_stdout.rst:4 +#, fuzzy +msgid "Переопределение стандартного вывода" msgstr "Redirect stdout" +#: ../../root/redirect_stdout.rst:7 +msgid "О разделе" +msgstr "" + +#: ../../root/redirect_stdout.rst:9 +msgid "" +"``Argenta`` предоставляет гибкие механизмы для управления форматированием" +" вывода, включая использование динамических разделительных линий. Это " +"достигается за счет перехвата стандартного потока вывода (``stdout``), " +"что имеет свои особенности." +msgstr "" + +#: ../../root/redirect_stdout.rst:14 +msgid "Механизм перехвата ``stdout``" +msgstr "" + +#: ../../root/redirect_stdout.rst:16 +msgid "" +"По умолчанию ``Argenta`` перехватывает весь текст, который выводится в " +"``stdout`` внутри обработчика команды (``handler``). Это делается для " +"реализации **динамической длины разделителя**. Система анализирует весь " +"выведенный текст, находит самую длинную строку и использует её длину для " +"отрисовки верхней и нижней разделительных линий. Это создает аккуратный и" +" визуально согласованный интерфейс, где вывод команды \"обернут\" в " +"рамку, идеально подогнанную под его содержимое." +msgstr "" + +#: ../../root/redirect_stdout.rst:19 +msgid "Побочные эффекты перехвата ``stdout``" +msgstr "" + +#: ../../root/redirect_stdout.rst:21 +msgid "" +"Главный побочный эффект этого механизма проявляется при использовании " +"функций, которые одновременно ожидают ввод от пользователя и выводят " +"текст-приглашение. Классический пример — стандартная функция ``input()``." +msgstr "" + +#: ../../root/redirect_stdout.rst:30 +msgid "" +"При включенном перехвате ``stdout`` текст-приглашение ``\"Введите ваше " +"имя: \"`` **не будет выведен в консоль немедленно**. Он попадет в буфер, " +"и пользователь увидит только мигающий курсор, ожидающий ввода. Текст " +"приглашения будет выведен только после того, как выполнение всего " +"обработчика завершится, вместе с остальным буферизованным выводом. Это " +"может сбить пользователя с толку и является пограничным случаем, " +"требующим внимания при разработке." +msgstr "" + +#: ../../root/redirect_stdout.rst:35 +msgid "Отключение перехвата ``stdout`` с помощью ``disable_redirect_stdout``" +msgstr "" + +#: ../../root/redirect_stdout.rst:37 +msgid "" +"Чтобы решить проблему с ``input()`` и другими подобными функциями, в " +"конструкторе класса ``Router`` предусмотрен специальный аргумент:" +msgstr "" + +#: ../../root/redirect_stdout.rst:39 +msgid "**disable_redirect_stdout** (``bool``, по умолчанию ``False``)" +msgstr "" + +#: ../../root/redirect_stdout.rst:41 +msgid "" +"Если при создании роутера установить ``disable_redirect_stdout=True``, то" +" для всех команд этого роутера механизм перехвата ``stdout`` будет " +"отключен." +msgstr "" + +#: ../../root/redirect_stdout.rst:46 +msgid "" +"В этом случае ``input()`` будет работать как обычно, и пользователь сразу" +" увидит приглашение \"Как вас зовут?\"." +msgstr "" + +#: ../../root/redirect_stdout.rst:51 +msgid "Типы разделительных линий" +msgstr "" + +#: ../../root/redirect_stdout.rst:53 +msgid "" +"``Argenta`` поддерживает два типа разделительных линий, которые можно " +"настроить при инициализации ``App``:" +msgstr "" + +#: ../../root/redirect_stdout.rst:55 +msgid "**DynamicDividingLine()**" +msgstr "" + +#: ../../root/redirect_stdout.rst:56 +msgid "" +"Это поведение по умолчанию. Длина линии динамически подстраивается под " +"самый длинный выведенный текст." +msgstr "" + +#: ../../root/redirect_stdout.rst:57 +msgid "" +"Требует включенного перехвата ``stdout`` (т.е. " +"``disable_redirect_stdout=False`` на роутере)." +msgstr "" + +#: ../../root/redirect_stdout.rst:59 +msgid "**StaticDividingLine(length: int = 25)**" +msgstr "" + +#: ../../root/redirect_stdout.rst:60 +msgid "" +"Линия имеет фиксированную длину (по умолчанию 25 символов), которую можно" +" настроить через аргумент `length`." +msgstr "" + +#: ../../root/redirect_stdout.rst:61 +msgid "" +"Используется автоматически для роутеров, где " +"``disable_redirect_stdout=True``, так как без перехвата вывода невозможно" +" определить необходимую динамическую длину." +msgstr "" + +#: ../../root/redirect_stdout.rst:64 +msgid "Настройка разделительной линии в `App`" +msgstr "" + +#: ../../root/redirect_stdout.rst:66 +msgid "" +"Вы можете глобально задать тип разделительной линии для всего приложения " +"через аргумент ``dividing_line`` в конструкторе ``App``." +msgstr "" + +#: ../../root/redirect_stdout.rst:74 +msgid "Итоговое поведение" +msgstr "" + +#: ../../root/redirect_stdout.rst:80 +msgid "``disable_redirect_stdout`` на ``Router``" +msgstr "" + +#: ../../root/redirect_stdout.rst:81 +msgid "Тип линии в ``App``" +msgstr "" + +#: ../../root/redirect_stdout.rst:82 +msgid "Фактическое поведение" +msgstr "" + +#: ../../root/redirect_stdout.rst:83 +msgid "``input()`` работает корректно?" +msgstr "" + +#: ../../root/redirect_stdout.rst:84 ../../root/redirect_stdout.rst:88 +msgid "``False`` (по умолчанию)" +msgstr "" + +#: ../../root/redirect_stdout.rst:85 ../../root/redirect_stdout.rst:93 +msgid "``DynamicDividingLine``" +msgstr "" + +#: ../../root/redirect_stdout.rst:86 +msgid "Динамическая линия, длина по содержимому" +msgstr "" + +#: ../../root/redirect_stdout.rst:87 ../../root/redirect_stdout.rst:91 +msgid "Нет" +msgstr "" + +#: ../../root/redirect_stdout.rst:89 ../../root/redirect_stdout.rst:97 +msgid "``StaticDividingLine``" +msgstr "" + +#: ../../root/redirect_stdout.rst:90 ../../root/redirect_stdout.rst:98 +msgid "Статическая линия указанной длины" +msgstr "" + +#: ../../root/redirect_stdout.rst:92 ../../root/redirect_stdout.rst:96 +msgid "``True``" +msgstr "" + +#: ../../root/redirect_stdout.rst:94 +msgid "**Принудительно статическая линия** (длина по умолч.)" +msgstr "" + +#: ../../root/redirect_stdout.rst:95 ../../root/redirect_stdout.rst:99 +msgid "Да" +msgstr "" + +#: ../../root/redirect_stdout.rst:101 +msgid "" +"Таким образом, для создания интерактивных команд, требующих ввода от " +"пользователя, всегда отключайте перехват ``stdout`` на соответствующем " +"роутере. Для всех остальных команд можно оставить поведение по умолчанию." +msgstr "" + diff --git a/docs/root/api/app/index.rst b/docs/root/api/app/index.rst index a9c7754..1b5efc8 100644 --- a/docs/root/api/app/index.rst +++ b/docs/root/api/app/index.rst @@ -1,7 +1,101 @@ .. _root_api_app_index: App -**************** +=== + +Объект ``App`` является центральной сущностью библиотеки ``Argenta``. Он выступает в роли ядра вашего консольного приложения, отвечая за его конфигурацию, управление жизненным циклом, обработку команд и взаимодействие с пользователем. ``App`` координирует работу всех остальных компонентов, таких как роутеры, обработчики команд и системные сообщения. + +------ + +Инициализация +------------- + +.. code:: rust + + AVAILABLE_DIVIDING_LINES: TypeAlias = StaticDividingLine | DynamicDividingLine + DEFAULT_DIVIDING_LINE: StaticDividingLine = StaticDividingLine() + + DEFAULT_PRINT_FUNC: Printer = Console().print + DEFAULT_AUTOCOMPLETER: AutoCompleter = AutoCompleter() + DEFAULT_EXIT_COMMAND: Command = Command("Q", description="Exit command") + +.. code:: python + + def __init__(self, *, prompt: str = "What do you want to do?\n\n", + initial_message: str = "Argenta\n", + farewell_message: str = "\nSee you\n", + exit_command: Command = DEFAULT_EXIT_COMMAND, + system_router_title: str | None = "System points:", + ignore_command_register: bool = True, + dividing_line: AVAILABLE_DIVIDING_LINES = DEFAULT_DIVIDING_LINE, + repeat_command_groups: bool = True, + override_system_messages: bool = False, + autocompleter: AutoCompleter = DEFAULT_AUTOCOMPLETER, + print_func: Printer = DEFAULT_PRINT_FUNC) -> None + +Создает и настраивает экземпляр приложения `Argenta`. + + * ``prompt``: Строка-приглашение, которая отображается перед вводом каждой команды. По умолчанию: **"What do you want to do?\\n\\n"**. + * ``initial_message``: Приветственное сообщение, которое выводится при запуске приложения. + * ``farewell_message``: Прощальное сообщение при завершении работы приложения. + * ``exit_command``: Сущность команды, которая будет маркирована как команда для выхода из приложения. + * ``system_router_title``: Заголовок для системного роутера, который содержит команду выхода и другие системные команды. + * ``ignore_command_register``: Если **True** (по умолчанию), регистр введенных команд будет игнорироваться при поиске обработчика. + * ``dividing_line``: Объект, управляющий стилем разделительной линии. Может быть **StaticDividingLine** или **DynamicDividingLine**. + * ``repeat_command_groups``: Если **True** (по умолчанию), описание доступных команд будет выводиться перед каждым вводом. + * ``override_system_messages``: Если **True** (по умолчанию), стандартное форматирование системных сообщений (цвета, ASCII-арт) будет отключено. + * ``autocompleter``: Объект, отвечающий за логику автодополнения команд. + * ``print_func``: Функция, используемая для вывода всех системных сообщений. По умолчанию используется ``rich.console.Console().print``. + +Основные методы +--------------- + +.. py:method:: include_router(self, router: Router) -> None + + Регистрирует один `Router` в приложении. Все команды, определенные в этом роутере, становятся доступными для вызова. + + :param router: Объект роутера, который нужно зарегистрировать. + +.. py:method:: include_routers(self, *routers: Router) -> None + + Регистрирует несколько роутеров одновременно. Является удобной оберткой над `include_router`. + + :param routers: Последовательность объектов `Router` для регистрации. + +.. py:method:: add_message_on_startup(self, message: str) -> None + + Добавляет дополнительное текстовое сообщение, которое будет выведено на экран при запуске приложения, сразу после `initial_message`. + + :param message: Строка с сообщением. + +Методы установки обработчиков +------------------------------- + +`App` позволяет гибко настраивать реакцию на различные события, такие как ошибки ввода или ввод неизвестной команды. + +.. py:method:: set_description_message_pattern(self, handler: DescriptionMessageGenerator) -> None + + Устанавливает пользовательский шаблон для форматирования строки, описывающей доступную команду (триггер + описание). + +.. py:method:: set_incorrect_input_syntax_handler(self, handler: NonStandardBehaviorHandler[str]) -> None + + Устанавливает обработчик, который вызывается при некорректном синтаксисе флагов в введенной команде. + +.. py:method:: set_repeated_input_flags_handler(self, handler: NonStandardBehaviorHandler[str]) -> None + + Устанавливает обработчик для ситуации, когда пользователь вводит один и тот же флаг несколько раз. + +.. py:method:: set_unknown_command_handler(self, handler: NonStandardBehaviorHandler[InputCommand]) -> None + + Устанавливает обработчик, который срабатывает, если введенная команда не была найдена ни в одном из зарегистрированных роутеров. + +.. py:method:: set_empty_command_handler(self, handler: EmptyCommandHandler) -> None + + Устанавливает обработчик для случая, когда пользователь отправляет пустую строку вместо команды. + +.. py:method:: set_exit_command_handler(self, handler: NonStandardBehaviorHandler[Response]) -> None + + Позволяет переопределить стандартное поведение при вызове команды выхода. По умолчанию просто выводится `farewell_message`. .. toctree:: :hidden: diff --git a/docs/root/api/command/flags.rst b/docs/root/api/command/flags.rst index 4048b00..e605b8d 100644 --- a/docs/root/api/command/flags.rst +++ b/docs/root/api/command/flags.rst @@ -1,20 +1,18 @@ .. _root_api_command_flags: Flags -**************** +====== -.. _root_api_command_flag: - Flag -**************** +===== InputFlags -**************** +=========== .. _root_api_command_input_flag: InputFlag -**************** +========== diff --git a/docs/root/api/index.rst b/docs/root/api/index.rst index 06d9a53..eeaf22a 100644 --- a/docs/root/api/index.rst +++ b/docs/root/api/index.rst @@ -1,8 +1,21 @@ .. _root_api_index: -Публичный API -**************** +Публичное API +============= + +Описание раздела +---------------- + +В данном разделе приводятся сведения о публичной части интерфейса библиотеки: + +- Классы и функции, предназначенные для прямой интеграции в сторонние приложения. +- Советы по совместимости, ограничения и поддерживаемые сценарии использования. +- Примеры типовой интеграции, подробные сигнатуры методов и описание возвращаемых сущностей. +- Гарантии стабильности API, поддержка и обратная совместимость между версиями. + +Интерфейсы, не указанные в этом разделе, считаются внутренними и не подлежат использованию вне самой библиотеки. При разработке собственных решений рекомендуем обращаться именно к описанным здесь компонентам — это даст стабильность и гарантии на будущее развитие ваших продуктов с использованием ``Argenta``. + .. toctree:: :hidden: @@ -12,3 +25,4 @@ orchestrator/index command/index response + \ No newline at end of file diff --git a/docs/root/contributing.rst b/docs/root/contributing.rst index aa639b9..1f817f0 100644 --- a/docs/root/contributing.rst +++ b/docs/root/contributing.rst @@ -15,7 +15,7 @@ * Поставить звезду проекту * Написать о нем в ``Twitter`` - * Ссылаться на этот проект в `Readme` вашего проекта + * Ссылаться на этот проект в ``Readme`` вашего проекта * Упомянуть проект на местных встречах и рассказать о нем друзьям/коллегам .. _Содержание: @@ -53,7 +53,7 @@ Если вы хотите задать вопрос, мы предполагаем, что вы уже ознакомились с доступной `Документацией `_. -Прежде чем задать вопрос, лучше всего поискать существующие `Issue `_, которые могут вам помочь. Если вы нашли подходящий ``issue``, но все еще нуждаетесь в разъяснениях, вы можете написать свой вопрос в этом ``issue``. Также рекомендуется сначала поискать ответы в интернете. +Прежде чем задать вопрос, лучше всего поискать существующие `Issues `_, которые могут вам помочь. Если вы нашли подходящий ``issue``, но все еще нуждаетесь в разъяснениях, вы можете написать свой вопрос в этом ``issue``. Также рекомендуется сначала поискать ответы в интернете. Если после этого вы все еще чувствуете необходимость задать вопрос, мы рекомендуем следующее: diff --git a/mock/mock_app/routers.py b/mock/mock_app/routers.py index eed2aaf..2295b3b 100644 --- a/mock/mock_app/routers.py +++ b/mock/mock_app/routers.py @@ -1,6 +1,7 @@ from argenta.command import Command, PredefinedFlags, Flags, Flag, PossibleValues from argenta.response import Response from argenta import Router +from argenta.router.defaults import system_router work_router: Router = Router(title="Work points:", disable_redirect_stdout=True) @@ -20,6 +21,6 @@ def command_help(response: Response): response.update_data({"data": [_ for _ in range(9999999)]}) -@work_router.command("run") +@system_router.command("run") def command_start_solving(response: Response): print(response.get_data())