Refine Russian docs around bundled examples

docs/examples.ru.md

@@ -1,10 +1,15 @@
 # Примеры DrawZero
 
-На этой странице собрана галерея примеров, демонстрирующих возможности библиотеки DrawZero.
+На этой странице собрана галерея из 21 примера, которые поставляются вместе с библиотекой
+DrawZero. Каждый блок ниже подтягивает код напрямую из каталога
+`src/drawzero/examples`, поэтому вы видите ровно те же исходники, что и при установке
+пакета. Используйте галерею как справочник: переходите от иллюстраций к коду, сверяйтесь
+с комментариями в исходниках и экспериментируйте у себя в редакторе.
 
 ## Начало работы
 
-Эти примеры показывают самые основы вывода изображения на экран.
+Эти примеры показывают, как вывести первые примитивы на экран и разобраться с базовым
+циклом `run()`.
 
 ### 00_hello_world.py
 
@@ -22,7 +27,8 @@
 
 ## Использование циклов и цветов
 
-Узнайте, как использовать циклы для создания более сложных узоров и как работать с разными цветами.
+Используйте циклы и случайные значения, чтобы быстро получать выразительные узоры и
+научиться передавать цвета в именованном и RGB-форматах.
 
 ### 02_loops_and_rgb_colors.py
 
@@ -47,7 +53,8 @@
 
 ## Точки и черепашья графика
 
-Класс `Pt` позволяет использовать векторную математику и команды рисования в стиле "черепашки".
+Класс `Pt` из публичного API работает и как вектор, и как "черепаха". Эти примеры показывают
+арифметику точек и построение фигур через повороты и смещения.
 
 ### 05_points.py
 
@@ -65,7 +72,8 @@
 
 ## Анимация
 
-Оживите свои рисунки с помощью анимации.
+Здесь начинается анимация: цикл `while True`, `tick()`, `clear()` и дополнительные эффекты,
+которые встречаются в примерах `07`–`10`.
 
 ### 07_animation_circles.py
 
@@ -97,7 +105,8 @@
 
 ## Продвинутое рисование
 
-Изучите более продвинутые возможности, такие как прозрачность, рендеринг изображений и цветовые градиенты.
+Эти скрипты раскрывают дополнительные функции библиотеки: прозрачность, загрузку изображений
+и градиенты, на которых основаны многие визуальные эффекты из исходников.
 
 ### 11_transparency_and_line_width.py
 
@@ -122,7 +131,7 @@
 
 ## Интерактивные примеры
 
-Сделайте свои творения интерактивными, реагируя на ввод с клавиатуры и мыши.
+Добавьте управление с клавиатуры и мыши, чтобы рисунки реагировали на пользователя в реальном времени.
 
 ### 14_animation_close_vertex.py
 
@@ -154,7 +163,7 @@
 
 ## Игры
 
-Создавайте простые игры с помощью библиотеки DrawZero.
+И, наконец, несколько мини-игр, собранных из примитивов, анимации и обработки ввода.
 
 ### 18_game_stars.py
 

docs/examples_overview.ru.md

@@ -1,30 +1,37 @@
 # Обзор примеров
 
-Пакет `src/drawzero/examples` содержит запускаемые скрипты, которые служат одновременно дымовыми тестами и демонстрацией использования. В таблице ниже показано назначение каждого скрипта, чтобы вы могли выбрать подходящую отправную точку при поиске неисправностей или расширении функциональности.
+Каталог `src/drawzero/examples` содержит 21 сценарий, которые авторы библиотеки
+используют как регрессионные тесты и обучающие демо. Они демонстрируют реальные
+приёмы из исходного кода и дополняют разделы документации. В таблице ниже указано,
+какую тему поднимает каждый файл и за какими функциями стоит следить, когда вы
+изучаете пример или ищете отправную точку для своей задачи.
 
-| Файл | Фокус | Ключевые идеи |
+| Файл | О чём пример | На что обратить внимание |
 | --- | --- | --- |
-| `00_hello_world.py` | Первый рендеринг на холсте | Рисует холст с рамкой, разделяет текст на два языка и запускает цикл `run()`. |
-| `01_grid_and_coordinates.py` | Обзор системы координат | Рендерит вспомогательную сетку `grid()`, затем аннотирует различные примитивы в известных координатах. |
-| `02_loops_and_rgb_colors.py` | Искусство, управляемое циклом | Использует цикл `for` и случайные кортежи RGB для рисования вертикальных полос различной высоты. |
-| `03_simple_objects.py` | Каталог примитивов | Демонстрирует каждый примитив рисования (линии, круги, повернутые прямоугольники, многоугольники, выравнивание текста). |
-| `04_loops_sin_plot.py` | Построение математических графиков | Строит синусоиду, сшивая короткие отрезки линий вдоль оси X. |
-| `05_points.py` | Помощник [`Pt`](pt.md) как вектор/черепаха | Показывает, как класс `Pt` поддерживает арифметику, движение и вращение в стиле черепахи в циклах. |
-| `06_turtle_style.py` | Рисование многоугольников с помощью [`Pt`](pt.md) | Вращает экземпляр `Pt` для построения правильных многоугольников для сторон от 3 до 10 с использованием операций черепахи. |
-| `07_animation_circles.py` | Минимальный цикл анимации | Изменяет положение, радиус и цвет круга с течением времени, вызывая `tick()` на каждом кадре. |
-| `08_animation_traffic_light.py` | Анимация на основе состояний | Повторно использует помощника для рисования светофора и использует `sleep()` для переключения цветов. |
-| `09_animation_rectangles.py` | Сложная анимация | Сочетает математику `Pt` с логикой вращения/орбиты, прозрачностью и условными эффектами. |
-| `10_animation_planets.py` | Орбитальное движение | Вычисляет круговое движение для пары планета/луна и перерисовывает каждый кадр. |
-| `11_transparency_and_line_width.py` | Альфа-смешивание и толщина обводки | Демонстрирует различные значения альфа-канала и толщины линий на кругах, прямоугольниках, многоугольниках и эллипсах. |
-| `12_images.py` | Рендеринг изображений | Загружает `cat.png` из папки примеров, демонстрирует масштабирование и альфа-канал при выводе изображений. |
-| `13_gradients.py` | Помощник [Gradient](gradient.md) | Создает несколько шкал `Gradient` и визуализирует их с помощью сложенных прямоугольников. |
-| `14_animation_close_vertex.py` | Анимация графа близости | Перемещает случайные узлы `Pt` с циклическим движением, рисует линии между соседними парами и использует оверлей FPS. |
-| `15_animation_firework.py` | Система частиц | Реализует классы `Particle` и `Firework` с обновлениями физики, свечением на основе градиента и логикой очистки. |
-| `16_keyboard_and_mouse.py` | Обработка ввода | Читает массивы состояний клавиш и очереди событий для перемещения квадрата, отслеживания вводимых символов и следования за мышью. |
-| `17_mouse_tube.py` | Эффект следа мыши | Захватывает `mouse_pos()` на каждом кадре, выращивает концентрические круги с градиентом по мере их старения. |
-| `18_game_stars.py` | Мини-игра 3D-звездное поле | Использует датаклассы, случайные звезды и управление WASD/QE для навигации по псевдо-3D полю. |
-| `19_game_colors.py` | Игра на реакцию | Отображает слова-цвета в сравнении с фактическими цветами, обрабатывает выбор кнопок мыши со штрафами по времени. |
-| `20_game_racing.py` | Многопользовательская мини-игра | Назначает отдельные привязки клавиш для каждой машины, прокручивает предварительно вычисленную дорогу и ведет счет для каждого игрока. |
-| `99_errors.py` | Демонстрация сообщений об ошибках | Принудительно вызывает ошибки проверки в режиме `EJUDGE_MODE`, чтобы продемонстрировать локализованную диагностику, выдаваемую конвертерами. |
+| `00_hello_world.py` | Первый вывод на холст | Последовательность `from drawzero import *`, вызов `run()` и базовая рамка окна. |
+| `01_grid_and_coordinates.py` | Система координат | Вспомогательная сетка `grid()`, подписи текста и расположение фигур по известным точкам. |
+| `02_loops_and_rgb_colors.py` | Генеративное искусство | Цикл `for`, случайные RGB‑кортежи и построение полос разной высоты. |
+| `03_simple_objects.py` | Каталог примитивов | Все основные функции рисования: линии, окружности, многоугольники, эллипсы и выравнивание текста. |
+| `04_loops_sin_plot.py` | Графики функций | Построение синусоиды из коротких отрезков с шагом по оси X. |
+| `05_points.py` | Векторный помощник [`Pt`](pt.md) | Арифметика, нормализация и черепашьи операции `Pt` в циклах. |
+| `06_turtle_style.py` | Черепашьи многоугольники | Повороты `Pt`, конструирование правильных многоугольников и заливка. |
+| `07_animation_circles.py` | Минимальная анимация | Связка `tick()`, `clear()` и параметров окружности, которые меняются каждый кадр. |
+| `08_animation_traffic_light.py` | Машина состояний | Комбинация функций рисования с `sleep()` для плавного переключения цветов. |
+| `09_animation_rectangles.py` | Сложные траектории | Использование `Pt`, прозрачности и условных эффектов для движения нескольких объектов. |
+| `10_animation_planets.py` | Орбитальная система | Расчёт кругового движения планеты и спутника с перерисовкой на каждом кадре. |
+| `11_transparency_and_line_width.py` | Прозрачность и обводка | Сравнение значений `alpha` и `line_width` на разных примитивах. |
+| `12_images.py` | Работа с изображениями | Загрузка `cat.png`, масштабирование и использование альфа‑канала при выводе. |
+| `13_gradients.py` | Помощник [Gradient](gradient.md) | Создание палитр и их визуализация в виде составных прямоугольников. |
+| `14_animation_close_vertex.py` | Ближайшие соседи | Случайные вершины `Pt`, линии между ближайшими парами и счётчик FPS. |
+| `15_animation_firework.py` | Система частиц | Классы `Particle`/`Firework`, обновление физики и постэффекты на градиентах. |
+| `16_keyboard_and_mouse.py` | Обработка ввода | Глобальные очереди клавиатуры и мыши, слежение за курсором и ввод текста. |
+| `17_mouse_tube.py` | Светящийся след мыши | `mouse_pos()` на каждом кадре, нарастающие круги и плавное затухание. |
+| `18_game_stars.py` | Псевдо‑3D полёт | Датаклассы, управление WASD/QE и перемещение звёзд с перспективой. |
+| `19_game_colors.py` | Игра на реакцию | Сравнение цвета текста и фона, обработка кликов и штраф по таймеру. |
+| `20_game_racing.py` | Гоночный экран на двоих | Индивидуальные привязки клавиш, прокрутка трека и отдельный счёт для игроков. |
+| `99_errors.py` | Сообщения об ошибках | Примеры исключений и логирование диагностики в режиме `EJUDGE_MODE`. |
 
-При добавлении новых примеров следите за тем, чтобы их можно было безопасно импортировать (тесты импортируют модули напрямую), и предпочитайте конечные циклы или защищайте бесконечные циклы блоком `if __name__ == "__main__"`.
+Все эти файлы можно безопасно импортировать: тесты проекта делают именно так, чтобы
+убедиться в корректности API. Если вы добавляете собственный пример, оставляйте
+бесконечные циклы только внутри блока `if __name__ == "__main__":` или заменяйте их
+конечными циклами, чтобы импорт не зависал.

docs/index.ru.md

@@ -1,16 +1,18 @@
 # DrawZero
 
-DrawZero помогает рисовать на виртуальном холсте почти без предварительной настройки. В
-документации ниже собраны самые полезные разделы, чтобы вы могли сразу перейти к
-нужной теме.
+DrawZero помогает рисовать на виртуальном холсте почти без предварительной настройки.
+Ниже собраны разделы, которые чаще всего нужны на старте. Каждый из них основан на
+оригинальных исходниках библиотеки и пересекается с галереей из 21 учебного примера,
+которую авторы поставляют вместе с пакетом.
 
 ## Быстрая навигация
 
 - [Установка](installation.md) – установите библиотеку и запустите свой первый
   скрипт.
-- [Графические примитивы](primitives.md) – изучите все основные фигуры, цвета и
-  функции для работы с текстом.
-- [Анимация](animation.md) – разберитесь с игровым циклом, функцией `tick()` и следами
-  движения для создания анимированных скетчей.
-- [Обзор примеров](examples_overview.md) – просмотрите запускаемые демо-скрипты,
-  которые объединяют примитивы и функции для анимации.
+- [Графические примитивы](primitives.md) – разберите ключевые фигуры, именованные и
+  RGB‑цвета, текст и вспомогательные функции, которые лежат в основе почти каждого
+  примера из пакета `src/drawzero/examples`.
+- [Анимация](animation.md) – разберитесь с игровым циклом, функцией `tick()` и приёмами
+  создания следов, которые используются в динамических примерах (см. скрипты `07`–`17`).
+- [Обзор примеров](examples_overview.md) – просмотрите все 21 сценарий от авторов,
+  чтобы быстрее сопоставлять документацию с реальным кодом.