docs: add new page in docs - Flags

docs/conf.py

@@ -40,10 +40,10 @@ html_theme_options = {
   "nav_links": [
          {
              "title": "Sponsor me",
-             "url": "https://github.com/sponsors/koloideal",
-             "external": True
+             "url": "https://github.com/sponsors/koloideal"
          },
      ],
     "github_url": "https://github.com/koloideal/Argenta",
     "linkedin_url": "https://www.linkedin.com/in/dmitry-shevelev-31b9a6324"
 }
+

docs/index.rst

@@ -4,7 +4,7 @@
    contain the root `toctree` directive.
 
 Argenta
-*******
+=======
 
 **Библиотека для построения модульных CLI-приложений с простым и приятным API.**
 

docs/root/api/command/flags.rst

@@ -4,7 +4,7 @@ Flags
 ****************
 
 
-.. _flag:
+.. _root_api_command_flag:
 
 Flag
 ****************
@@ -14,7 +14,7 @@ InputFlags
 ****************
 
 
-.. _input_flag:
+.. _root_api_command_input_flag:
 
 InputFlag
 ****************

docs/root/error_handling.rst

@@ -1,9 +1,9 @@
 .. _root_error_handling:
 
-Обработка ошибок
+Стандартная обработка ошибок
 ==========================================
 
-Конфигурация
+О разделе
 ------------
 
 ``Argenta`` в рантайме вызывает исключения в пограничных случаях пользовательского ввода.
@@ -29,7 +29,7 @@
 ``UnprocessedInputFlagException``: Необрабатываемый ввод от пользователя
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Исключение вызывается, когда пользователь вводит команду с некорректным синтаксисом и парсер не может
+Исключение вызывается, когда пользователь вводит команду с некорректным синтаксисом и как следствие парсер не может
 *распарсить* её. В большинстве случаев это означат, что проблема в синтаксисе введённых флагов команды, подробнее о
 флагах и их синтаксисе в :ref:`Flags <root_flags>`.
 

docs/root/flags.rst

@@ -2,3 +2,63 @@
 
 Флаги вводимых команд
 =====================
+
+Флаги (или параметры) — это специальные аргументы, которые конечный юзер может добавлять к командам, чтобы управлять их поведением. 
+
+Синтаксис флагов
+-----------------
+
+Обобщённый синтаксис выглядит так:
+
+.. code-block:: py
+
+   <command_name> <flag_prefix: Literal['-', '--', '---']><flag_name> <flag_value: Optional>
+
+То есть, у флага обязательно должен быть префикс, который может быть одним, двум или трем минусам. После префикса следует имя флага, без
+пробела, после, через пробел, идёт значение флага, если оно есть.
+
+Два типа флагов
+---------------
+
+Флаги бывают двух основных видов: без значений (переключатели) и со значениями. ``Argenta`` позволяет регистрировать и вводить флаги обоих типов в любой последовательности  для одной команды.
+
+.. note::
+    Ошибки валидации значений являются пассивными, их не нужно обрабатывать явно. У каждого инстанса :ref:`InputFlag <root_api_command_input_flag>` есть поле ``status``, по которому можно определить результат валидации флага. **Конкретная реализация и описание API вы можете найти в разделе** :ref:`Flag <root_api_command_flag>`.
+
+При регистрации флага вы можете указать допустимые для него значения, по умолчанию любое введённое значение для флага будет валидным. Допустимые значения можно указать различными способами:
+
+Ограничение по списку возможных значений
+----------------------------------------
+
+Вы можете заранее определить список допустимых значений для флага.
+
+**Пример:**
+
+Предположим, у вас есть флаг ``--format``, который может принимать только значения ``json`` или ``xml``.
+
+.. code-block:: bash
+
+   # Эта команда сработает
+   export --format json
+
+   # А эта вызовет ошибку валидации, так как "csv" нет в списке разрешённых
+   export --format csv
+
+Проверка с помощью регулярных выражений
+-----------------------------------------
+
+Для более сложных проверок вы можете использовать регулярные выражения. Это особенно полезно, когда значение должно соответствовать определённому формату, например, быть email-адресом, датой или номером телефона.
+
+**Пример:**
+
+Допустим, флаг ``--email`` должен принимать только корректные email-адреса.
+
+.. code-block:: bash
+
+   # Сработает, так как значение соответствует формату email
+   send --email "user@example.com"
+
+   # Вызовет ошибку валидации, так как "user_example.com" — некорректный email
+   send --email "user_example.com"
+
+Встроенная валидация избавляет вас от необходимости писать ручные проверки и делает ваш код более декларативным.

docs/root/overriding_formatting.rst

@@ -1,6 +1,6 @@
 .. _root_overriding_formatting:
 
-Переопределение форматирования
-*****************************************
+Стандартное форматирование
+************************
 
 ндааааааааааааааа

docs/root/redirect_stdout.rst

@@ -1,6 +1,6 @@
 .. _root_redirect_stdout:
 
 
-Перенаправление стандартного вывода
+Переопределение стандартного вывода
 ***********************************