docs

docs/root/api/app/dividing_lines.rst

@@ -1,4 +1,81 @@
 .. _root_api_app_dividing_lines:
 
-DividingLines
-****************
+Dividing Lines
+==============
+
+Разделительные линии в ``Argenta`` играют важную роль в визуальном оформлении консольного интерфейса. Они используются для структурирования вывода, отделения блоков информации друг от друга (например, вывода команды от следующего приглашения к вводу).
+Библиотека предлагает два подхода к управлению разделительными линиями: статический и динамический, каждый из которых имеет свои преимущества и сценарии использования.
+
+----
+
+Класс ``StaticDividingLine``
+--------------------------
+
+``StaticDividingLine`` — это класс, который создает разделительную линию **фиксированной** длины. Длина и символ-заполнитель задаются при инициализации объекта. Этот тип линии полезен, когда вам нужен предсказуемый и унифицированный внешний вид интерфейса, независимо от содержимого вывода.
+
+.. code-block:: python
+   :linenos:
+   
+      def __init__(self, unit_part: str = "-", *, 
+                   length: int = 25) -> None
+
+Создает экземпляр статической разделительной линии.
+
+* ``unit_part``: Символ, который будет использоваться для построения линии. Учитывается только первый символ строки. По умолчанию: ``-``.
+* ``length``: Целое число, определяющее фиксированную длину линии в символах. Является keyword-only аргументом. По умолчанию: ``25``.
+
+-----
+
+Класс ``DynamicDividingLine``
+---------------------------
+
+``DynamicDividingLine`` представляет собой более "умный" подход. Этот класс создает линию, длина которой **динамически** подстраивается под самую длинную строку, выведенную в консоль, в рамках выполнения одной команды. Это достигается за счет механизма перехвата `stdout`. В результате разделительные линии всегда идеально обрамляют выводимый контент, что выглядит очень аккуратно.
+
+.. code-block:: python
+  :linenos:
+
+   __init__(self, unit_part: str = "-") -> None
+
+Создает экземпляр динамической разделительной линии.
+
+* ``unit_part``: Символ, который будет использоваться для построения линии. По умолчанию: ``-``.
+
+Длина для этой линии не задается при инициализации, так как она вычисляется автоматически во время выполнения.
+
+.. warning::
+    Обязательно почитайте про нюансы использования динамических линий и перехвата ``stdout`` в :ref:`этом разделе<root_redirect_stdout>`.
+
+Назначение и использование
+--------------------------
+
+Выбор между статической и динамической линией зависит от ваших потребностей в конкретном приложении или даже для конкретного `Router`.
+
+*   **`StaticDividingLine`** идеально подходит, если:
+    *   Вам нужен строгий, консистентный дизайн.
+    *   Вы используете роутеры с отключенным перехватом `stdout` (`disable_redirect_stdout=True`), так как в этом случае динамическое вычисление длины невозможно.
+
+*   **`DynamicDividingLine`** (используется по умолчанию) является предпочтительным выбором, если:
+    *   Вы хотите, чтобы интерфейс выглядел аккуратно и адаптивно.
+    *   Вывод ваших команд имеет разную длину, и вы хотите, чтобы рамки всегда соответствовали контенту.
+
+Тип разделительной линии для всего приложения задается при инициализации `App` через параметр `dividing_line`.
+
+Пример конфигурации
+--------------------
+
+.. code-block:: python
+
+    from argenta.app import App
+    from argenta.app.dividing_line.models import StaticDividingLine, DynamicDividingLine
+
+    # Создание статической линии из символов "=" длиной 40
+    static_line = StaticDividingLine(unit_part="=", length=40)
+
+    # Создание динамической линии из символов "*"
+    dynamic_line = DynamicDividingLine(unit_part="*")
+
+    # Приложение со статической линией
+    app_with_static_line = App(dividing_line=static_line)
+
+    # Приложение с динамической линией (поведение по умолчанию, но с кастомным символом)
+    app_with_dynamic_line = App(dividing_line=dynamic_line)