Update documentation and code snippets

docs/index.rst

@@ -19,15 +19,15 @@ Argenta
 
 Argenta предназначена для создания приложений, работающих в собственном контексте (scope). Это означает, что при запуске пользователь входит в интерактивную сессию, где ему доступна вся реализованная вами функциональность.
 
-Один из ключевых принципов библиотеки — цикличность. После выполнения команды пользователь остаётся в интерактивной сессии, в отличие от таких библиотек, как ``argparse``, ``click`` и ``typer``. Выход из сессии контролируется самим пользователем.
+Один из ключевых принципов библиотеки — цикличность. После выполнения команды пользователь остаётся в интерактивной сессии, в отличие от таких библиотек, как ``argparse``, ``click`` и ``typer``. Выход из сессии контролируется пользователем.
 
 **Ключевые особенности:**
 
-*   **Интерактивные сессии**. В отличие от традиционных CLI-инструментов, Argenta создаёт циклические сессии, позволяя пользователю выполнять команды последовательно, не перезапуская приложение.
+*   **Интерактивные сессии**: В отличие от традиционных CLI-инструментов, ``Argenta`` создаёт циклические сессии, позволяя пользователю выполнять команды последовательно, не перезапуская приложение.
-*   **Декларативный синтаксис**. Команды и их обработчики объявляются с помощью простых декораторов, что делает код чистым и интуитивно понятным.
+*   **Декларативный синтаксис**: Команды и их обработчики объявляются с помощью простых декораторов, что делает код чистым и интуитивно понятным.
-*   **Нативный DI**. Благодаря интеграции с `dishka <https://dishka.readthedocs.io/en/stable/>`_, вы можете легко внедрять зависимости прямо в обработчики команд, что упрощает их тестирование и переиспользование.
+*   **Нативный DI**: Благодаря интеграции с `dishka <https://dishka.readthedocs.io/en/stable/>`_, вы можете легко внедрять зависимости прямо в обработчики команд, что упрощает их тестирование и переиспользование.
-*   **Автоматическая валидация и парсинг**. Библиотека берёт на себя обработку флагов и аргументов командной строки, включая их парсинг, валидацию и преобразование типов.
+*   **Автоматическая валидация и парсинг**: Библиотека берёт на себя обработку флагов и аргументов командной строки, включая их парсинг, валидацию и преобразование типов.
-*   **Гибкая настройка**. Вы можете легко кастомизировать системные сообщения, форматирование вывода и т.д.
+*   **Гибкая настройка**: Вы можете легко кастомизировать системные сообщения, форматирование вывода и т.д.
 
 -----
 

docs/root/api/app/dividing_lines.rst

@@ -5,10 +5,10 @@ Dividing Lines
 
 Разделительные линии в ``Argenta`` используются для визуального структурирования вывода и отделения блоков информации друг от друга. Библиотека предлагает два типа линий: статическую и динамическую.
 
-----
+-----
 
 ``StaticDividingLine``
------------------------------
+----------------------
 
 ``StaticDividingLine`` создаёт разделительную линию **фиксированной** длины. Этот тип линии полезен для создания предсказуемого и унифицированного интерфейса.
 
@@ -26,7 +26,7 @@ Dividing Lines
 -----
 
 ``DynamicDividingLine``
-------------------------------
+-----------------------
 
 ``DynamicDividingLine`` создаёт линию, длина которой **динамически** подстраивается под самую длинную строку в выводе команды. Это требует перехвата ``stdout``, в результате чего разделители идеально обрамляют выводимый контент.
 
@@ -47,7 +47,7 @@ Dividing Lines
 -----
 
 Назначение и использование
---------------------------
+---------------------------
 
 Выбор между статической и динамической линией зависит от ваших задач.
 

docs/root/api/command/flag.rst

@@ -67,7 +67,7 @@ string_entity
    @property
    string_entity(self) -> str
 
-Возвращает строковое представление флага в формате `prefix + name`.
+Возвращает строковое представление флага в формате ``prefix + name``.
 
 :return: Строковое представление флага
 

docs/root/api/command/input_flag.rst

@@ -51,7 +51,7 @@ string_entity
    @property
    string_entity(self) -> str
 
-Возвращает строковое представление флага в формате `prefix + name`.
+Возвращает строковое представление флага в формате ``prefix + name``.
 
 :return: Строковое представление флага
 
@@ -70,7 +70,7 @@ __str__
 
 Возвращает строковое представление флага вместе с его значением.
 
-:return: Строка в формате `флаг значение`.
+:return: Строка в формате ``флаг значение``.
 
 **Пример использования:**
 

docs/root/api/command/input_flags.rst

@@ -83,10 +83,10 @@ add_flag
 
 Добавляет введённый флаг в коллекцию.
 
-:param flag: Флаг типа `InputFlag` для добавления.
+:param flag: Флаг типа ``InputFlag`` для добавления.
 :return: None.
 
-Метод добавляет флаг в конец списка `flags`. Используется для динамического расширения коллекции.
+Метод добавляет флаг в конец списка ``flags``. Используется для динамического расширения коллекции.
 
 .. note::
    Этот метод используется редко, так как `InputFlags` обычно создаётся автоматически. Однако он может быть полезен для тестирования или ручного создания коллекций.
@@ -109,7 +109,7 @@ add_flags
 
 Добавляет в коллекцию список введённых флагов.
 
-:param flags: Список флагов типа `InputFlag` для добавления.
+:param flags: Список флагов типа ``InputFlag`` для добавления.
 :return: None.
 
 Метод расширяет коллекцию, добавляя в неё все флаги из переданного списка. Эффективен для пакетного добавления.
@@ -128,7 +128,7 @@ add_flags
 Обработка всех флагов с проверкой статусов
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Пример демонстрирует итерацию по всем введённым флагам с проверкой их статусов валидации:
+**Пример использования:**
 
 .. literalinclude:: ../../../code_snippets/input_flags/snippet10.py
    :linenos:

docs/root/api/orchestrator/argparser.rst

@@ -25,8 +25,10 @@ ArgParser
 * ``description``: Описание приложения для отображения в справке.
 * ``epilog``: Дополнительная информация для отображения в конце справки.
 
+-----
+
 Атрибуты
----------------------------
+--------
 
 .. py:attribute:: parsed_argspace: ArgSpace
 
@@ -39,13 +41,14 @@ ArgParser
 
 -----
    
+-----
+
 Лучшие практики
-------------------------
+---------------
 
 Использовать атрибут ``parsed_argspace`` рекомендуется только на этапе настройки приложения. В обработчиках лучшей практикой является получение ``ArgSpace`` через DI. Подробнее см. :ref:`здесь <root_dependency_injection>`.
 
-Пример использования
+**Пример использования:**
---------------------
 
 .. literalinclude:: ../../../code_snippets/argparser/snippet.py
    :language: python

docs/root/api/orchestrator/argspace.rst

@@ -75,8 +75,8 @@ InputArgument
 
 -----
 
-Примеры испольования
+Примеры использования
---------------------
+---------------------
 
 ``ArgSpace`` используется для доступа к значениям аргументов после запуска приложения. Типичный сценарий включает обработку аргументов через ``ArgParser`` и последующее извлечение значений из ``ArgSpace``.
 
@@ -87,6 +87,8 @@ InputArgument
    
 Доступ к аргументам из обработчиков осуществляется с помощью ``di``. Подробнее см. :ref:`здесь <root_dependency_injection>`.
 
+**Пример использования:**
+
 .. literalinclude:: ../../../code_snippets/argspace/snippet2.py
    :linenos:
 

docs/root/api/orchestrator/arguments.rst

@@ -35,8 +35,8 @@ ValueArgument
 :param help: Сообщение для справки (``--help``)
 :param possible_values: Список допустимых значений 
 :param default: Значение по умолчанию, если аргумент не передан
-:param is_required: Если ``True``, аргумент становится обязательным, если не передать при запуске приложение не запустится
+:param is_required: Если ``True``, аргумент становится обязательным. Если не передать при запуске, приложение не запустится
-:param is_deprecated: Если ``True``, помечает аргумент как устаревший, если передать при запуске, то будет выведено предупреждение в консоль
+:param is_deprecated: Если ``True``, помечает аргумент как устаревший. Если передать при запуске, будет выведено предупреждение в консоль
 
 **Пример использования:**
 
@@ -115,7 +115,7 @@ InputArgument
 Создаёт экземпляр обработанного входного аргумента.
 
 :param name: Имя аргумента
-:param value: Значение аргумента. Для ``BooleanArgument`` — **True**, если аргумент передан и **False**, если нет; для **ValueArgument** — введённая строка 
+:param value: Значение аргумента. Для ``BooleanArgument`` — **True**, если аргумент передан, и **False**, если нет; для ``ValueArgument`` — введённая строка 
 :param founder_class: Класс-родитель, из которого был создан аргумент (``BooleanArgument`` или ``ValueArgument``)
 
 **Атрибуты:**
@@ -128,8 +128,8 @@ InputArgument
 
    Значение аргумента. Тип зависит от исходного класса:
 
-* Для ``BooleanArgument``: **True**, если аргумент был передан.
+   * Для ``BooleanArgument``: **True**, если аргумент был передан
-* Для ``ValueArgument``: строка с переданным значением или значением по умолчанию
+   * Для ``ValueArgument``: строка с переданным значением или значением по умолчанию
 
 .. py:attribute:: founder_class
 

docs/root/api/orchestrator/index.rst

@@ -47,12 +47,11 @@ Orchestrator
 Назначение и использование
 ----------------------------
 
-``Orchestrator`` абстрагирует сложность, связанную с настройкой ``di`` и парсингом стартовых аргументов. Типичный сценарий использования выглядит так.
+``Orchestrator`` абстрагирует сложность, связанную с настройкой ``di`` и парсингом стартовых аргументов.
 
 Такой подход разделяет ответственности: ``App`` отвечает за логику интерактивной сессии, а ``Orchestrator`` — за подготовку окружения и запуск приложения.
 
-Пример использования
+**Пример использования:**
---------------------
 
 .. literalinclude:: ../../../code_snippets/orchestrator/snippet.py
    :language: python

docs/root/dependency_injection.rst

@@ -18,17 +18,23 @@
 .. note::
    ``argenta.di.FromDishka`` является алиасом для ``dishka.FromDishka``, и они полностью взаимозаменяемы.
 
+**Пример использования:**
+
 .. literalinclude:: ../code_snippets/dependency_injection/snippet.py
    :language: python
    :linenos:
 
-``Argenta`` с помощью ``dishka`` разрешит зависимость по типу ``Connection`` и внедрит её. Но прежде чем использовать зависимость, её необходимо объявить в провайдере.
+``Argenta`` с помощью ``dishka`` разрешит зависимость по типу ``Connection`` и внедрит её. Но прежде чем использовать зависимость, её необходимо объявить в провайдере:
+
+**Пример использования:**
 
 .. literalinclude:: ../code_snippets/dependency_injection/snippet2.py
    :language: python
    :linenos:
    
-После создания провайдера его необходимо зарегистрировать в оркестраторе.
+После создания провайдера его необходимо зарегистрировать в оркестраторе:
+
+**Пример использования:**
 
 .. literalinclude:: ../code_snippets/dependency_injection/snippet3.py
    :language: python
@@ -51,7 +57,7 @@
 
 ``Argenta`` поставляется со встроенным провайдером, который даёт доступ к важным системным зависимостям без дополнительной настройки. Например, вы можете получить объект ``ArgSpace``, который содержит аргументы командной строки, переданные при запуске приложения.
 
-Пример получения объекта ``ArgSpace`` и вывода в консоль значения аргумента `type`:
+**Пример использования:**
 
 .. literalinclude:: ../code_snippets/dependency_injection/snippet4.py
    :language: python
@@ -59,8 +65,8 @@
    
 -----
 
-Обмен данными между хендлерами
+Обмен данными между обработчиками
-------------------------------
+----------------------------------
 
 Помимо DI, обработчики могут обмениваться данными в рамках сессии через **объект контекста**. В ``Argenta`` эту роль выполняет объект ``DataBridge``.
 

docs/root/error_handling.rst

@@ -3,16 +3,13 @@
 Обработка ошибок
 ==========================================
 
-О разделе
+``Argenta`` выбрасывает исключения в пограничных случаях, связанных с пользовательским вводом.
-------------
+По умолчанию они обрабатываются системными обработчиками, но вы можете их переопределить. Это делается с помощью сеттеров экземпляра ``App`` вида ``.set_*_handler()``. Подробнее о каждом из них рассказано :ref:`ниже <possible_errors>`.
-
-Argenta выбрасывает исключения в пограничных случаях, связанных с пользовательским вводом.
-По умолчанию они обрабатываются системными хэндлерами, но вы можете их переопределить. Это делается с помощью сеттеров экземпляра ``App`` вида ``.set_*_handler()``. Подробнее о каждом из них рассказано :ref:`ниже <possible_errors>`.
 
 .. note::
-    Ни одно исключение не остаётся необработанным, так как для каждого случая предусмотрен стандартный хэндлер. Поэтому переопределение является опциональным.
+    Ни одно исключение не остаётся необработанным, так как для каждого случая предусмотрен стандартный обработчик. Поэтому переопределение является опциональным.
 
-Пример переопределения обработчика для пустой команды:
+**Пример использования:**
 
 .. literalinclude:: ../code_snippets/error_handling/snippet.py
     :language: python
@@ -29,7 +26,7 @@ Argenta выбрасывает исключения в пограничных с
 
 Это исключение выбрасывается, когда парсер не может обработать команду из-за некорректного синтаксиса. Чаще всего это связано с ошибкой в синтаксисе флагов. Подробнее о них можно прочитать в разделе :ref:`Flags <root_flags>`.
 
-Стандартный хэндлер выводит в консоль
+Стандартный обработчик выводит в консоль:
 
 .. code-block::  shell
 
@@ -37,7 +34,7 @@ Argenta выбрасывает исключения в пограничных с
 
 Для переопределения используется сеттер ``.set_incorrect_input_syntax_handler()``. Он принимает на вход обработчик с сигнатурой ``Callable[[str], None]``, где единственный аргумент — это строка с необработанной командой.
 
-Пример кода, переопределяющего хэндлер ввода команды с некорректным синтаксисом:
+**Пример использования:**
 
 .. literalinclude:: ../code_snippets/error_handling/snippet2.py
    :language: python
@@ -53,7 +50,7 @@ Argenta выбрасывает исключения в пограничных с
 .. note::
     Сравнение на равенство у регистрируемых флагов (``Flag``) происходит иначе, подробнее в :ref:`Flag <root_flags>`.
 
-Стандартный хэндлер выводит в консоль
+Стандартный обработчик выводит в консоль:
 
 .. code-block::  shell
 
@@ -61,7 +58,7 @@ Argenta выбрасывает исключения в пограничных с
 
 Для переопределения используется сеттер ``.set_repeated_input_flags_handler()``. Он принимает на вход обработчик с сигнатурой ``Callable[[str], None]``, где единственный аргумент — это строка с необработанной командой.
 
-Пример кода, переопределяющего хэндлер ввода команды с повторяющимися флагами:
+**Пример использования:**
 
 .. literalinclude:: ../code_snippets/error_handling/snippet3.py
    :language: python
@@ -74,7 +71,7 @@ Argenta выбрасывает исключения в пограничных с
 
 Исключение выбрасывается, если пользователь ввёл пустую строку или строку, состоящую только из пробельных символов (``\n``, ``\t``, пробел и т.д.).
 
-Стандартный хэндлер выводит в консоль
+Стандартный обработчик выводит в консоль:
 
 .. code-block::  shell
 
@@ -82,7 +79,7 @@ Argenta выбрасывает исключения в пограничных с
 
 Для переопределения используется сеттер ``.set_empty_command_handler()``. Он принимает на вход обработчик с сигнатурой ``Callable[[], None]`` (без аргументов).
 
-Пример кода, переопределяющего хэндлер ввода пустой команды:
+**Пример использования:**
 
 .. literalinclude:: ../code_snippets/error_handling/snippet4.py
     :language: python
@@ -97,7 +94,7 @@ Argenta выбрасывает исключения в пограничных с
 
 Это поведение активируется, когда пользователь вводит команду, которая не зарегистрирована ни в одном из роутеров и не является псевдонимом (alias) для существующей команды.
 
-Стандартный хэндлер выводит в консоль
+Стандартный обработчик выводит в консоль:
 
 .. code-block::  shell
 
@@ -105,7 +102,7 @@ Argenta выбрасывает исключения в пограничных с
 
 Для переопределения используется сеттер ``.set_unknown_command_handler()``. Он принимает на вход обработчик с сигнатурой ``Callable[[InputCommand], None]``, где аргумент — объект :ref:`InputCommand <root_api_command_input_command>`.
 
-Пример кода, переопределяющего хэндлер ввода неизвестной команды:
+**Пример использования:**
 
 .. literalinclude:: ../code_snippets/error_handling/snippet5.py
     :language: python
@@ -118,7 +115,7 @@ Argenta выбрасывает исключения в пограничных с
 
 Это поведение активируется, когда пользователь вводит команду, помеченную как команда выхода.
 
-Стандартный хэндлер выводит в консоль текст и завершает работу приложения.
+Стандартный обработчик выводит в консоль текст и завершает работу приложения:
 
 .. code-block::  shell
 
@@ -126,7 +123,7 @@ Argenta выбрасывает исключения в пограничных с
 
 Для переопределения используется сеттер ``.set_exit_command_handler()``. Он принимает на вход обработчик с сигнатурой ``Callable[[Response], None]``, где аргумент — объект :ref:`Response <root_api_response>`.
 
-Пример кода, переопределяющего хэндлер ввода команды выхода:
+**Пример использования:**
 
 .. literalinclude:: ../code_snippets/error_handling/snippet6.py
     :language: python

docs/root/flags.rst

@@ -92,7 +92,7 @@
 ~~~~~~~~~~~~~~~~~
 
 **Время жизни и область действия**
-  Аргументы передаются один раз при запуске приложения и сохраняют действие на весь период работы(скоуп **APP**). Флаги наоборот локальны и живут в рамках скоупа **REQUEST**.
+  Аргументы передаются один раз при запуске приложения и сохраняют действие на весь период работы (скоуп **APP**). Флаги наоборот локальны и живут в рамках скоупа **REQUEST**.
 
 **Частота изменения**
   Для изменения аргументов необходимо перезапустить приложение. Флаги можно менять между каждым вводом команды без остановки приложения.

docs/root/redirect_stdout.rst

@@ -54,6 +54,8 @@
 
 Если при создании роутера установить ``disable_redirect_stdout=True``, механизм перехвата ``stdout`` будет отключён для всех его обработчиков.
 
+**Пример использования:**
+
 .. literalinclude:: ../code_snippets/redirect_stdout/sample.py
    :language: python
    :linenos:
@@ -82,6 +84,8 @@
 
 Вы можете глобально задать тип разделителя для всего приложения через аргумент ``dividing_line`` в конструкторе ``App``.
 
+**Пример использования:**
+
 .. literalinclude:: ../code_snippets/redirect_stdout/sample2.py
    :language: python
    :linenos:

docs/root/testing.rst

@@ -3,12 +3,12 @@
 
 В этом разделе описаны практики тестирования приложений на основе ``Argenta``. Примеры основаны на фактическом публичном API.
 
-Модульное тестирование хендлеров
+Модульное тестирование обработчиков
---------------------------------
+------------------------------------
 
-Обработчики в Argenta — обычные функции. Их удобно тестировать как чистые функции, не поднимая весь цикл приложения. Рекомендуются ``unittest`` или ``pytest``.
+Обработчики в ``Argenta`` — обычные функции. Их удобно тестировать как чистые функции, не поднимая весь цикл приложения. Рекомендуются ``unittest`` или ``pytest``.
 
-Пример для простого хендлера без DI:
+**Пример использования:**
 
 .. literalinclude:: ../code_snippets/testing/simple_handler_unittest.py
    :language: python
@@ -19,7 +19,9 @@
 Тестирование с внедрением зависимостей (DI)
 -------------------------------------------
 
-Если хендлеру нужны зависимости, используйте ``dishka`` и интеграцию Argenta:
+Если обработчику нужны зависимости, используйте ``dishka`` и интеграцию ``Argenta``:
+
+**Пример использования:**
 
 .. literalinclude:: ../code_snippets/testing/di_handler_unittest.py
    :language: python
@@ -30,7 +32,9 @@
 Интеграционное тестирование приложения
 --------------------------------------
 
-Для более высокого уровня тестов собирайте ``App`` и ``Router`` и вызывайте хендлеры через парсинг команд, обходя бесконечный цикл ввода. Это даёт близкое к реальности поведение без необходимости симулировать ``stdin``.
+Для более высокого уровня тестов собирайте ``App`` и ``Router`` и вызывайте обработчики через парсинг команд, обходя бесконечный цикл ввода. Это даёт близкое к реальности поведение без необходимости симулировать ``stdin``.
+
+**Пример использования:**
 
 .. literalinclude:: ../code_snippets/testing/app_integration_unittest.py
    :language: python
@@ -39,13 +43,15 @@
 -----
 
 E2E-тестирование цикла
-------------------------------------
+----------------------
 
 Полный запуск цикла ``start_polling`` можно покрывать через подпроцесс с передачей строк в ``stdin``. Это тяжелее и обычно не требуется. Если всё же необходимо — пример ниже.
 
-.. danger ::
+.. danger::
     Обязательно передавайте строковый триггер команды выхода последним элементом в списке, который передаёте в контекстном менеджере при патче ``input`` как аргумент ``side_effects``, иначе тестируемое приложение будет ожидать ввода следующей команды и не сможет корректно завершиться.
 
+**Пример использования:**
+
 .. literalinclude:: ../code_snippets/testing/app_e2e_test.py
    :language: python
    :linenos: