mirror of
https://github.com/StepanovPlaton/SSAUGenerator.git
synced 2026-10-31 10:18:29 +04:00
StepanovPlaton
bf7816ab7c
- Move projects into content/<project>/{docx,pptx} with shared assets/
- Flatten config paths; output = project name in project folder
- Add pptx --init scaffold; remove docx exe build
- Add feature-complete content/example; ignore content/* except example
- Rewrite README and AGENTS.md
112 lines
6.4 KiB
Markdown
112 lines
6.4 KiB
Markdown
# AGENTS.md — управление проектом SSAU Generator
|
||
|
||
Репозиторий содержит два независимых генератора отчётных документов из Markdown.
|
||
Этот файл описывает управление проектом в целом. Правила работы с конкретным
|
||
документом — в [`docx/AGENTS.md`](docx/AGENTS.md) и [`pptx/AGENTS.md`](pptx/AGENTS.md).
|
||
|
||
## Что использовать по запросу пользователя
|
||
|
||
- Просит **сгенерировать документ** (отчёт, DOCX, пояснительную записку,
|
||
лабораторную работу) — используйте генератор в папке `docx/`.
|
||
- Просит **сгенерировать презентацию** (PPTX, слайды) — используйте генератор в
|
||
папке `pptx/`.
|
||
|
||
Команды запускаются из корня репозитория; генератору указывается `config.yaml`
|
||
нужного проекта. Содержимое документа задаётся Markdown-файлами и `config.yaml`
|
||
проекта, а не кодом генератора.
|
||
|
||
## Правила работы над проектом
|
||
|
||
- **Уточните название проекта.** Если пользователь не указал, над каким проектом
|
||
ведётся работа, сначала спросите его. Проект — это папка `content/<проект>/`.
|
||
- **Один проект за сессию.** В рамках одной сессии работайте только над одним
|
||
проектом.
|
||
- **Создание — только через `--init`.** Новый проект создавайте командами с флагом
|
||
`--init` (см. ниже): они формируют правильную структуру и общий каталог
|
||
ресурсов.
|
||
- **Имя результата = имя проекта.** Документ и презентация собираются в папку
|
||
проекта, а имя файла совпадает с именем проекта:
|
||
`content/<проект>/<проект>.docx` и `content/<проект>/<проект>.pptx`.
|
||
Соответствующий путь задаётся ключом `output` в `config.yaml`.
|
||
- **Пересобирайте после правок.** При любом изменении исходных файлов
|
||
(`config.yaml`, `*.md`, ресурсов в `assets/`) заново запускайте сборку docx
|
||
и/или pptx, чтобы результат соответствовал исходникам.
|
||
|
||
## Структура репозитория
|
||
|
||
```
|
||
ssau-generator/
|
||
├── docx/ # генератор DOCX (только код)
|
||
├── pptx/ # генератор PPTX (только код)
|
||
├── tools/ # общий plantuml.jar (не в git)
|
||
├── content/ # проекты (в git хранится только example)
|
||
│ └── example/
|
||
│ ├── assets/ # общие ресурсы проекта (для docx и pptx)
|
||
│ ├── docx/ # config.yaml + *.md
|
||
│ └── pptx/ # config.yaml + slides/
|
||
├── AGENTS.md # этот файл
|
||
└── README.md
|
||
```
|
||
|
||
## Проекты и каталог content
|
||
|
||
- **Один проект = одна папка** `content/<проект>/`.
|
||
- Внутри проекта при необходимости лежат папки `docx/` и `pptx/`.
|
||
- **Общие ресурсы проекта** (титульный лист, задники, изображения, исходники
|
||
`.puml`) размещаются в `content/<проект>/assets/` и используются обоими
|
||
генераторами. В `docx/` и `pptx/` внутри проекта хранятся только `config.yaml`
|
||
и Markdown.
|
||
- Папки `content/*` добавлены в `.gitignore`; в репозитории хранится только
|
||
`content/example/`. Рабочие проекты пользователя коммитить не нужно.
|
||
|
||
## Создание нового проекта
|
||
|
||
Проект создаётся командами с флагом `--init` — они формируют структуру и общие
|
||
ресурсы автоматически:
|
||
|
||
```powershell
|
||
# только документ DOCX
|
||
node docx/src/cli.js --content content/<проект>/docx --init
|
||
|
||
# только презентация PPTX
|
||
node pptx/src/cli.js -c content/<проект>/pptx/config.yaml --init
|
||
|
||
# оба генератора (каталог content/<проект>/assets/ создаётся первым вызовом
|
||
# и переиспользуется вторым)
|
||
```
|
||
|
||
После создания отредактируйте `config.yaml` и Markdown; общие ресурсы
|
||
(титульный лист, задники, изображения, `.puml`) положите в
|
||
`content/<проект>/assets/`.
|
||
|
||
## Сборка
|
||
|
||
```powershell
|
||
# Документ DOCX
|
||
node docx/src/cli.js --content content/<проект>/docx --check
|
||
node docx/src/cli.js --content content/<проект>/docx
|
||
|
||
# Презентация PPTX
|
||
node pptx/src/cli.js -c content/<проект>/pptx/config.yaml --check
|
||
node pptx/src/cli.js -c content/<проект>/pptx/config.yaml
|
||
```
|
||
|
||
Результат: `content/<проект>/<проект>.docx` или
|
||
`content/<проект>/<проект>.pptx` (имя и путь задаются ключом `output` в
|
||
`config.yaml`). После правок исходников пересобирайте файлы.
|
||
|
||
## Требования
|
||
|
||
- Node.js 18+, зависимости устанавливаются командой `npm install` в `docx/` и
|
||
`pptx/`.
|
||
- Java 11+ и файл `tools/plantuml.jar` (не хранится в git) — для рендеринга схем
|
||
PlantUML (`.puml`).
|
||
|
||
## Правила
|
||
|
||
- Для сборки документа не редактируйте код генераторов — меняйте `config.yaml`
|
||
и Markdown проекта.
|
||
- Не коммитьте содержимое `content/`, кроме `content/example/`.
|
||
- Не храните ресурсы внутри `docx/` и `pptx/` — общие файлы живут в
|
||
`content/<проект>/assets/`.
|