docs: update README, CONFIG and pyproject.toml for --send feature
- README: add --send flag to features, usage examples, full flag list; replace black/isort with ruff in dev section; add email config template variables docs - CONFIG: new email section with all fields documented, --send usage examples, error handling and flag compatibility table - pyproject.toml: remove unused black and isort from dev dependencies and their tool configs (project uses ruff for both lint and format)
This commit is contained in:
90
README.md
90
README.md
@@ -17,10 +17,11 @@ CLI-инструмент для генерации отчётов по зада
|
||||
- Экспорт в ODT, CSV, Markdown, HTML, JSON и Excel (.xlsx).
|
||||
- Excel-отчёт с merge-ячейками по проекту/версии, итогами, автошириной, автофильтром и закреплённой шапкой.
|
||||
- Сводка по времени (`--summary`).
|
||||
- YAML-конфиг (`~/.config/redmine-reporter/config.yml`): шаблон имени файла, путь по умолчанию, период, SMTP.
|
||||
- YAML-конфиг (`~/.config/redmine-reporter/config.yml`): шаблон имени файла, путь по умолчанию, период, email.
|
||||
- Умное разрешение `--output`: bare-формат (`xlsx`) → путь по шаблону, без расширения → автодописывание.
|
||||
- `--commit`: автосохранение отчёта в файл + фиксация периода в YAML-конфиге для следующего запуска.
|
||||
- Понятные сообщения об ошибках Redmine API (401/403/5xx, таймаут, сеть).
|
||||
- `--send`: отправка отчёта по email через SMTP сразу после генерации.
|
||||
- Понятные сообщения об ошибках Redmine API, SMTP и файловой системы.
|
||||
- Загрузка альтернативного `.env` через `--config`.
|
||||
|
||||
## Установка
|
||||
@@ -89,11 +90,17 @@ email:
|
||||
from: bot@example.com
|
||||
to:
|
||||
- boss@example.com
|
||||
cc: []
|
||||
bcc: []
|
||||
subject: "Отчёт {author} за {period}"
|
||||
body_text: "Во вложении отчёт."
|
||||
attach: true
|
||||
```
|
||||
|
||||
Шаблон `output.filename` поддерживает `{author}`, `{from}`, `{to}`, `{date}` (DD_MM_YYYY), `{ext}`.
|
||||
|
||||
Шаблоны `email.subject` и `email.body_text` поддерживают `{author}`, `{period}` (строка диапазона, например `2026-06-01--2026-06-30`).
|
||||
|
||||
Подробнее: [docs/CONFIG.md](docs/CONFIG.md).
|
||||
|
||||
### `.env` (legacy)
|
||||
@@ -125,6 +132,8 @@ DEFAULT_TO_DATE=2026-01-31
|
||||
source .venv/bin/activate
|
||||
```
|
||||
|
||||
### Основные сценарии
|
||||
|
||||
Отчёт за период по умолчанию:
|
||||
|
||||
```bash
|
||||
@@ -164,41 +173,46 @@ redmine-reporter --compact
|
||||
redmine-reporter --debug
|
||||
```
|
||||
|
||||
Экспорт с явным путём:
|
||||
### Экспорт в файл
|
||||
|
||||
Явный путь:
|
||||
|
||||
```bash
|
||||
redmine-reporter --output report.xlsx
|
||||
redmine-reporter --output /path/to/report.odt
|
||||
```
|
||||
|
||||
Экспорт — только формат (путь и имя берутся из YAML-шаблона):
|
||||
Только формат (путь и имя берутся из YAML-шаблона):
|
||||
|
||||
```bash
|
||||
redmine-reporter --output xlsx # → output.dir/отчёт_01_07_2026.xlsx
|
||||
redmine-reporter --output odt # → output.dir/отчёт_01_07_2026.odt
|
||||
```
|
||||
|
||||
Экспорт — путь без расширения (дописывается `default_format` из конфига):
|
||||
Путь без расширения (дописывается `default_format` из конфига):
|
||||
|
||||
```bash
|
||||
redmine-reporter --output /tmp/report # → /tmp/report.xlsx (если default_format: xlsx)
|
||||
```
|
||||
|
||||
Без времени / с разбивкой по активностям:
|
||||
### Отправка по email (`--send`)
|
||||
|
||||
Отправить отчёт на email, указанный в YAML-конфиге (секция `email`):
|
||||
|
||||
```bash
|
||||
redmine-reporter --no-time
|
||||
redmine-reporter --by-activity
|
||||
redmine-reporter --by-activity --summary
|
||||
# Сохранить по шаблону и отправить
|
||||
redmine-reporter --date 2026-06-01--2026-06-30 --send
|
||||
|
||||
# С явным путём
|
||||
redmine-reporter --date 2026-06-01--2026-06-30 --output ~/report.xlsx --send
|
||||
|
||||
# Вместе с фиксацией периода
|
||||
redmine-reporter --date 2026-06-01--2026-06-30 --send --commit
|
||||
```
|
||||
|
||||
Сводка:
|
||||
Если секция `email` не настроена — ошибка с пояснением. При ошибке SMTP файл отчёта остаётся на диске, данные не теряются. Поддерживаются `to`, `cc`, `bcc`, TLS, отключение вложения (`attach: false`).
|
||||
|
||||
```bash
|
||||
redmine-reporter --summary
|
||||
```
|
||||
|
||||
Фиксация периода (`--commit`):
|
||||
### Фиксация периода (`--commit`)
|
||||
|
||||
```bash
|
||||
# Сгенерировать, сохранить в файл по шаблону, запомнить период
|
||||
@@ -215,6 +229,22 @@ redmine-reporter
|
||||
redmine-reporter --commit
|
||||
```
|
||||
|
||||
### Сводка и опции
|
||||
|
||||
Без времени / с разбивкой по активностям:
|
||||
|
||||
```bash
|
||||
redmine-reporter --no-time
|
||||
redmine-reporter --by-activity
|
||||
redmine-reporter --by-activity --summary
|
||||
```
|
||||
|
||||
Сводка:
|
||||
|
||||
```bash
|
||||
redmine-reporter --summary
|
||||
```
|
||||
|
||||
## Форматы вывода
|
||||
|
||||
| Формат | Особенности |
|
||||
@@ -226,6 +256,33 @@ redmine-reporter --commit
|
||||
| **JSON** | Массив объектов: `project`, `version`, `issue_id`, `subject`, `status`, `time`. |
|
||||
| **Excel (.xlsx)** | Merge cells, колонки `Hours`/`Spent Time`, итоги, автоширина, автофильтр, freeze panes. |
|
||||
|
||||
## Полный список флагов
|
||||
|
||||
```
|
||||
--date DATE Диапазон дат: YYYY-MM-DD--YYYY-MM-DD
|
||||
--compact Компактный текстовый вывод вместо таблицы
|
||||
--output PATH/FMT Путь к файлу (.odt/.csv/.md/.html/.json/.xlsx)
|
||||
или bare-формат (xlsx/odt/...) — путь из конфига
|
||||
--author NAME Переопределить имя автора
|
||||
--no-time Не включать затраченное время в таблицу
|
||||
--url URL Переопределить Redmine URL
|
||||
--api-key KEY Переопределить Redmine API key
|
||||
--config PATH Путь к альтернативному .env-файлу
|
||||
--verbose Подробный вывод
|
||||
--debug Отладочный вывод
|
||||
--version Показать версию и выйти
|
||||
--summary Вывести сводку по времени в stderr
|
||||
--user-id ID Redmine ID пользователя для отчёта
|
||||
--user-login LOGIN Логин пользователя Redmine
|
||||
--user-name NAME Полное имя пользователя Redmine
|
||||
--by-activity Разбить время по типам активности
|
||||
--init-config Сгенерировать YAML-конфиг и выйти
|
||||
--force Перезаписать существующий конфиг (с --init-config)
|
||||
--config-path PATH Путь к YAML-конфигу (по умолчанию ~/.config/redmine-reporter/config.yml)
|
||||
--commit Сохранить отчёт в файл и зафиксировать период в конфиге
|
||||
--send Отправить отчёт по email после сохранения
|
||||
```
|
||||
|
||||
## Разработка
|
||||
|
||||
Проверки перед коммитом:
|
||||
@@ -233,8 +290,7 @@ redmine-reporter --commit
|
||||
```bash
|
||||
pytest
|
||||
ruff check redmine_reporter tests
|
||||
black --check redmine_reporter tests
|
||||
isort --check-only redmine_reporter tests
|
||||
ruff format --check redmine_reporter tests
|
||||
mypy redmine_reporter
|
||||
```
|
||||
|
||||
|
||||
Reference in New Issue
Block a user