## 🗺️ Roadmap: как работать с шаблоном Этот раздел поможет тебе разобраться в структуре и содержании основных частей проекта: - Как организованы исходные файлы - Как работать с конфигурациями - Как настроены CI/CD и Docker --- ### 🗂️ Структура проекта 📜 Памятка по эмоджи: 📁 - Каталоги и папки 💻 - Настройки компьютера ⚙️ - Конфигурация шаблона 📋 - Текстовые файлы 📐 - Шаблонирование (копирование) 🕵️‍♂️ - Проверка (линтинг, безопасность) 🧱 - Исходный код (src) 🧪 - Тесты 🔄 - CI/CD процессы 🐳 - Докер 🧰 - Автоматизация (make) 📚 - Документация (Sphinx) Проект организован следующим образом: ```{toggle} projectTemplate/ ├── .github/ # GitHub Actions workflows │ └── workflows/ │ └── deploy_docs.yml # CI/CD для деплоя документации ├── .vscode/ # Настройки VS Code ├── configs/ # Конфигурационные файлы │ ├── config.py # Глобальные параметры проекта │ └── path_manager.py # Утилита для работы с путями ├── diagrams/ # Диаграммы UML │ ├── project_structure.puml # Архитектура проекта │ └── temp_containers.puml # Диаграмма контейнеров ├── docs/ # Документация проекта (Sphinx) │ └── index.rst # Основной файл документации ├── docker-compose.yaml # Конфигурация для Docker Compose ├── Dockerfile # Основной Dockerfile для сборки ├── Makefile # Полезные команды через make ├── README.md # Краткое описание проекта ├── requirements.txt # Зависимости Python ├── src/ # Исходный код │ ├── main.py # Основная точка входа │ └── utils/ # Вспомогательные утилиты │ └── logger.py # Логирование ├── tools/ # Вспомогательные скрипты │ ├── diagram_auto_update.py # Автоматическое обновление диаграмм │ └── print_structure.py # Вывод структуры проекта в терминал ├── tests/ # Тесты └── copier.yaml # Шаблон для генерации нового проекта └── .pre-commit-config.yaml # Конфигурация для Pre-Commit hooks └── .gitignore # Игнорируемые файлы для Git └── .dockerignore # Игнорируемые файлы для Docker └── .env # Переменные окружения └── .env.example # Пример файла .env └── {{ _copier_conf.answers_file }}.jinja # Шаблон Jinja для Copier ``` --- ### 💻 Настройки VS Code (.vscode/) Папка .vscode/ — это директория, которая позволяет настраивать Visual Studio Code для вашего проекта. Она содержит несколько важных файлов, которые могут быть использованы для улучшения вашего рабочего процесса и настройки IDE. #### ⚙️ settings.json Этот файл содержит настройки IDE, которые определяют, как будет выглядеть и вести себя редактор. - Отступы и форматирование кода (с указанием количества пробелов или символов для отступа). - Путь к интерпретатору Python для правильного выполнения кода. - Настройки линтинга и автозамены, чтобы поддерживать единый стиль кода по всему проекту. ```{eval-rst} .. toggle:: Показать .. literalinclude:: ../.vscode/settings.json :language: json :caption: settings.json ``` #### ⚙️ extensions.json Этот файл хранит список расширений для VS Code, которые могут улучшить опыт разработки. ```{eval-rst} .. toggle:: Показать .. literalinclude:: ../.vscode/extensions.json :language: json :caption: extensions.json ``` ```{note} VS Code автоматически предложит установить все необходимые расширения при открытии проекта. Но ты можешь сделать это вручную через меню расширений. ``` ##### Расширения, используемые в этом шаблоне | Категория | Расширение | Описание | |------------------------------------------|--------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------| | 🐍 **Python-разработка** | 🔧 [**Python (Microsoft)**](https://marketplace.visualstudio.com/items?itemName=ms-python.python) | Это основное расширение для разработки на Python. Поддерживает IntelliSense, линтинг, отладку, Jupyter Notebooks, виртуальные окружения и многое другое. | | | 🧠 [**Pylance (Microsoft)**](https://marketplace.visualstudio.com/items?itemName=ms-python.pylance) | Быстрый анализатор кода, предоставляющий автодополнение, переход по определению, подсветку ошибок и типизацию (type checking). | | | 🛑 [**Error Lens (Alexander)**](https://marketplace.visualstudio.com/items?itemName=usernamehw.errorlens) | Визуально выделяет ошибки в коде, делая их более заметными. | | | 🐙 [**GitHub Pull Requests and Issues (GitHub)**](https://marketplace.visualstudio.com/items?itemName=GitHub.vscode-pull-request-github) | Интеграция с GitHub: работа с pull requests, issues, обсуждениями прямо из редактора. | | 📦 **Работа с инфраструктурой и CI/CD** | ⚙️ [**Docker (Microsoft)**](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-docker) | Инструменты для работы с Docker: сборка образов, управление контейнерами, работа с Docker Compose и реестрами. | | | 📦 [**GitHub Actions (GitHub)**](https://marketplace.visualstudio.com/items?itemName=GitHub.github-actions) | Интеграция с GitHub Actions: просмотр пайплайнов, запуск, отладка и мониторинг выполнения CI/CD. | | 🧰 **Работа с файлами и форматами** | 🧩 [**Even Better TOML (tamasfe)**](https://marketplace.visualstudio.com/items?itemName=tamasfe.even-better-toml) | Расширенная поддержка TOML-файлов: автодополнение, валидация, форматирование. | | | 📄 [**MyST Highlight (ExecutableBookProject)**](https://marketplace.visualstudio.com/items?itemName=ExecutableBookProject.myst) | Поддержка синтаксиса MyST Markdown, используемого в Sphinx, для красивой документации. | | | 🖌️ [**Color Highlight (Sergii N)**](https://marketplace.visualstudio.com/items?itemName=sergi_n.color-highlight) | Подсвечивает цветовые значения (например, `#FF5733`) прямо в коде, показывая палитру. | | 📁 **Интерфейс и навигация** | 🎨 [**VSCode Icons (VSCode Icons Team)**](https://marketplace.visualstudio.com/items?itemName=VSCodeIcons.vscode-icons) | Иконки для файлов и папок в проводнике, улучшающие восприятие структуры проекта. | | | 💡 [**Better Comments (Aaron Bond)**](https://marketplace.visualstudio.com/items?itemName=aaron-bond.better-comments) | Выделяет комментарии разных типов (важные, TODO, FIXME и др.) цветом для лучшей читаемости. | | | 📌 [**Bookmarks (Alessandro Fragnani)**](https://marketplace.visualstudio.com/items?itemName=alefragnani.Bookmarks) | Позволяет ставить закладки в коде для быстрого перехода между важными участками. | | | 🧮 [**Fold Level (vikyd)**](https://marketplace.visualstudio.com/items?itemName=vikyd.vscode-foldlevel) | Удобное управление сворачиванием кода по уровням вложенности. | | 🛠️ **Сборка и автоматизация** | 🛠️ [**Makefile Tools (Microsoft)**](https://marketplace.visualstudio.com/items?itemName=ms-vscode.makefile-tools) | Позволяет работать с Makefile внутри VS Code — запуск целей, навигация, интеграция с редактором. | | 🌿 **Диаграммы и визуализация** | 🌿 [**PlantUML (jebbs)**](https://marketplace.visualstudio.com/items?itemName=jebbs.plantuml) | Поддержка создания диаграмм UML прямо в VS Code через синтаксис PlantUML. | --- ### ⚙️ Конфигурация #### 📋 requirements.txt Текстовый файл, в котором перечислены все зависимости, необходимые для работы с проектом. Например, так он выглядит для этого шаблона ```{eval-rst} .. toggle:: Показать .. literalinclude:: ../requirements.txt :language: text :caption: requirements.txt ``` #### 📁 configs Папка configs/ содержит файлы, которые отвечают за глобальные настройки проекта и управление путями. Эти файлы помогают централизовать параметры и упрощают управление проектом. ##### ⚙️ configs/config.py Этот файл содержит глобальные параметры проекта, такие как: - Пути к важным файлам и папкам (например, пути для логирования, сохранения данных или конфигураций). - Параметры окружения: например, настройки базы данных или API-ключи. Все эти параметры удобно собирать в одном месте, чтобы облегчить управление проектом и сделать его более гибким. ```{eval-rst} .. toggle:: Показать .. automodule:: configs.config :members: :undoc-members: :show-inheritance: ``` #### 📋 .env и .env.example Файл **.env** используется для хранения переменных окружения, которые могут использоваться в проекте. Это обычно конфиденциальные данные, такие как ключи API, пароли и другие настройки, которые не должны быть в коде. Файл **.env.example** представляет собой пример файла `.env`, который содержит шаблон для переменных окружения. Он помогает пользователям проекта понять, какие переменные необходимо настроить для работы приложения. ```{eval-rst} .. toggle:: Показать .. literalinclude:: ../.env.example :language: text :caption: .env.example ``` ```{tip} Перед началом работы создайте в директории проекта файл .env и скопируйте нужные переменные из .env.example. Не забудьте изменить configs/config.py в соответствии с вашим .env ``` ```{warning} Не включай файл .env в систему контроля версий (например, в Git) во избежание утечек ключей и секретов. В данном шаблоне используется `.gitignore`, чтобы исключить .env из коммитов. ``` #### 📐 Настройки copier ##### ⚙️ copier.yaml Файл copier.yaml является конфигурационным для инструмента copier, который используется для создания и копирования шаблонов проектов. Этот файл определяет, как будет происходить процесс клонирования шаблона и как будет обрабатываться ввод пользователя при создании нового проекта. Основные функции файла copier.yaml: - Настройки шаблона: Здесь задаются параметры для создания нового проекта, такие как вопросы для пользователя, которые будут заданы во время копирования шаблона. - Параметры клонирования: Определяет, какие файлы и папки будут включены в шаблон, а какие — исключены. Это позволяет гибко настраивать шаблоны под разные сценарии. - Обработка пользовательских данных: Этот файл может включать в себя переменные, которые заменяются на ответы пользователя при клонировании шаблона (например, имя проекта, версия и другие параметры). ```{eval-rst} .. toggle:: Показать .. literalinclude:: ../copier.yaml :language: yaml :caption: copier.yaml ``` ##### 📋 copier_conf.answers_file.jinja Шаблон Jinja используется в copier для настройки и генерации шаблонов проекта. Этот файл содержит динамические параметры и переменные, которые автоматически заменяются на ответы пользователя во время создания нового проекта. В Jinja-шаблонах обычно определяются шаблонные переменные, такие как название проекта, версия или другие параметры, которые нужно задать при клонировании шаблона. Эти переменные могут быть встроены в любые файлы шаблона, например, в конфигурационные файлы, код или документацию. ```{warning} После копирования шаблона в директории вашего проекта появится файл .copier.answers.yml НИКОГДА не изменяйте файл ответов вручную. Подробнее об этом читайте [в официальной документации](https://copier.readthedocs.io/en/stable/updating/#never-change-the-answers-file-manually) ``` --- #### ⚙️ Настройки pre-commit ##### 🕵️‍♂️ .pre-commit-config.yaml Конфигурация для инструмента **pre-Commit**, который управляет хуками для проверки кода перед его коммитом в репозиторий. В этом файле описываются используемые хуки для линтинга и других проверок. ```{eval-rst} .. toggle:: Показать .. literalinclude:: ../.pre-commit-config.yaml :language: yaml :caption: .pre-commit-config.yaml ``` --- #### ⚙️ Настройки исключений ##### 📋 .gitignore Файл **.gitignore** указывает Git, какие файлы и директории игнорировать в процессе контроля версий. Обычно он включает переменные окружения (.env), временные файлы, логи, кэш и другие файлы, которые не должны быть добавлены в репозиторий. ```{eval-rst} .. toggle:: Показать .. literalinclude:: ../.gitignore :language: text :caption: .gitignore ``` ##### 📋 .dockerignore Этот файл аналогичен `.gitignore`, но используется для исключения файлов из контекста сборки Docker. Он помогает уменьшить размер образа и ускорить сборку, исключая ненужные файлы и директории. ```{eval-rst} .. toggle:: Показать .. literalinclude:: ../.dockerignore :language: text :caption: .dockerignore ``` --- ### 🧱 Исходный код (src/) Исходный код проекта находится в директории `src/`. Он разделён на главный файл `main.py` и вспомогательные утилиты в папке `utils`. ```{note} В этой директории будет создаваться логика всего приложения, которое ты хочешь построить ``` #### 🧱 src/main.py Файл src/main.py является точкой входа в приложение. Он обычно содержит основную логику приложения, включая запуск процессов или инициализацию важных компонентов. Также в нем часто можно встретить код для вывода информации о начале работы приложения или настройку начальных параметров. Этот файл играет ключевую роль, так как запускает основные функции проекта. Это может быть как просто запуск консольного приложения, так и настройка веб-сервера или другого сервисного компонента. ```{eval-rst} .. toggle:: Показать .. automodule:: src.main :members: :undoc-members: :show-inheritance: ``` #### 🛠️ src/utils/logger.py Модуль src/utils/logger.py предоставляет базовую настройку логирования для проекта. Он отвечает за конфигурацию логера, который используется в других частях проекта для записи логов в консоль, файл или другие хранилища. Логирование — это важная часть приложения, которая помогает отслеживать события и ошибки в процессе работы программы. Этот модуль может быть настроен для записи логов с разными уровнями важности, такими как: - DEBUG — для детализированных сообщений, полезных при отладке. - INFO — для общих информационных сообщений. - WARNING — для предупреждений. - ERROR — для сообщений об ошибках. - CRITICAL — для критических ошибок. ```{eval-rst} .. toggle:: Показать .. automodule:: src.utils.logger :members: :undoc-members: :show-inheritance: ``` --- ### 🛠️ Инструменты (tools/) Папка `tools/` содержит вспомогательные скрипты, которые помогают улучшить разработку и поддерживать порядок в проекте. #### 🛠️ tools/diagram_auto_update.py Автоматически обновляет диаграммы PlantUML и генерирует `.svg` из `.puml` файлов. #### 🛠️ tools/print_structure.py Выводит текущую структуру проекта в терминал. Полезно для проверки состояния проекта перед коммитом. ```{note} Еще очень удобно уточнять контекст при общении с нейросетями, отправляя им структуру проекта ``` --- ### 🧪 Тестирование (tests/) Тесты находятся в директории `tests/`. ```{warning} В шаблоне пока не реализованы тесты ``` --- ### 📚 Документация (docs/) #### ⚙️ conf.py Конфигурационный файл для сборщика документации Sphinx. Этот файл содержит все настройки, необходимые для кастомизации входных и выходных данных Sphinx. Он выполняется как код на Python во время сборки, при этом текущая директория устанавливается как директория конфигурации. ```{error} Доделать вывод самого файла ``` ```{seealso} Подробнее см. в [документации Sphinx](https://www.sphinx-doc.org/en/master/usage/configuration.html): ``` #### 📋 index.rst Точка сборки документации Sphinx. Собирает все *.md в html страницы #### 📋 Файлы *.md Файлы написаны на языке [MyST Markdown](https://mystmd.org/guide). Описывают всю документацию #### 🧰 Makefile и make.bat Автоматизация локальной сборки документации ```{note} При локальной сборке документации рекомендуется всегда действовать по следующей схеме: Пример для Windows 1. очищаем кэш сборки .\docs\make.bat clean 2. собираем документацию .\docs\make.bat html Пример для Linux cd docs make clean make html ``` #### 📋 Диаграммы Диаграммы проекта находятся в директории `diagrams/`. Все диаграммы написаны на языке [PlantUML](https://plantuml.com/) и могут быть обновлены автоматически с помощью утилиты `tools/diagram_auto_update.py`. Рендер диаграмм происходит автоматически при помощи GitHub Actions --- ### 🐳 Docker Docker — это инструмент для создания, развертывания и управления контейнерами, который позволяет упаковать приложение и все его зависимости в один изолированный контейнер. Этот контейнер можно запускать в любой среде, что позволяет устранить проблемы с совместимостью, возникающие при запуске приложений на разных машинах. Контейнеры в Docker позволяют гарантировать, что приложение будет работать одинаково на всех устройствах, где установлен Docker, независимо от операционной системы или настроек окружения. Подробнее можно почитать [на хабре](https://habr.com/ru/companies/ruvds/articles/438796/) #### 🐳 Dockerfile Dockerfile — это текстовый файл с инструкциями, который описывает, как должен быть построен Docker-образ. В Dockerfile описываются шаги по установке зависимостей, настройке окружения и запуску приложения. ```{eval-rst} .. toggle:: Показать .. literalinclude:: ../Dockerfile :language: docker :caption: Dockerfile ``` #### 🐳 docker-compose.yaml Docker Compose — это инструмент для описания и запуска многоконтейнерных приложений. С помощью Compose можно настроить несколько контейнеров, каждый из которых выполняет свою задачу (например, один контейнер для приложения, другой для базы данных) и запускать их как единое приложение. Compose использует файл конфигурации docker-compose.yml, где прописывается вся необходимая информация о сервисах, сетях и томах. ##### Алгоритм деплоя нового приложения 1. Зайдите на VPS и разрешите нужный порт в ufw (файрволл) `````{note} Порт нужно указать в .env в переменной DOCKER_PORT ````{admonition} Подробнее о выборе порта :class: seealso :class: dropdown Лучше выбирать порты из диапазона 49152-65535 (динамические или частные порты), т.к они обычно не заняты важными службами. Разумнее всего проверить выбранный порт при помощи команд Проверка занятых портов ```bash sudo lsof -i -P -n | grep LISTEN ``` Проверка с помощью netstat ```bash sudo netstat -tuln ``` Проверка конкретного порта (например, 8080) ```bash sudo lsof -i :8080 ``` ```` ````` Пример для 443 порта ```bash sudo ufw allow 443/tcp sudo ufw status ``` ```{eval-rst} .. toggle:: Показать .. literalinclude:: ../docker-compose.yaml :language: yaml :caption: docker-compose.yaml ``` #### 🧰 Makefile Makefile — это текстовый файл, который используется системой сборки make для автоматизации процессов сборки и управления зависимостями в проекте. Преимущества использования Makefile: - Автоматизация: Позволяет автоматизировать повторяющиеся задачи, такие как создание окружений, установка зависимостей и запуск тестов. - Упрощение команд: В больших проектах, где нужно выполнять много шагов, Makefile позволяет упрощать команды. - Читаемость и удобство: Для новых участников проекта Makefile служит документом, который четко объясняет, как выполнять основные действия. ```{eval-rst} .. toggle:: Показать .. literalinclude:: ../Makefile :language: make :caption: Makefile ``` --- ### 🔄 CI/CD (GitHub Actions) #### Что такое CI/CD CI/CD (Continuous Integration / Continuous Delivery) — это процесс автоматизации разработки и развертывания приложений, который помогает ускорить внедрение изменений в проект. GitHub Actions предоставляет инструменты для автоматизации процессов, таких как тестирование, сборка, деплой и другие шаги, связанные с жизненным циклом проекта. Преимущества CI/CD с GitHub Actions: - Автоматизация деплоя: Каждый раз, когда в репозиторий вносятся изменения, документация обновляется автоматически. - Отсутствие необходимости вручную деплоить изменения: Процесс деплоя происходит без вмешательства пользователя. - Публичная доступность документации: Документация всегда доступна по постоянному URL через GitHub Pages. - Масштабируемость: Можно добавить дополнительные шаги в workflow, например, для тестирования или сборки приложения. #### Workflows В вашем проекте используется GitHub Actions для автоматизации деплоя документации на GitHub Pages. ```{eval-rst} .. toggle:: Показать .. literalinclude:: ../.github/workflows/deploy_docs.yml :language: yaml :caption: deploy_docs.yml ``` ---