hleb/md_to_gost
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

update 0.4.4
Python application / build (push) Has been cancelled
Details

Browse Source 
- update документация
- промт для ии полу конфигурируемый
This commit is contained in:
Igor20264
2026-09-06 11:04:01 +03:00
parent 638fd38d7f
commit 818a044aa1
26 changed files with 1987 additions and 457 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/README.md
+17
View File
@@ -0,0 +1,17 @@
# Документация md2gost
Конвертер Markdown → DOCX для учебных работ (ТЗ МИРЭА / ГОСТ 7.32, ПИС, АПИД).
## Содержание
1. [Быстрый старт](quickstart.md) — установка, первое окно, exe
2. [Синтаксис Markdown](markdown.md) — чем диалект отличается от обычного MD
3. [Схемы и диаграммы](schemes.md) — UML, Mermaid, настраиваемые схемы
4. [Типы документов](types.md) — coursework, practice, vkr, PIS_custom, APID_coursework
5. [CLI и GUI](cli-gui.md) — флаги и соответствие в интерфейсе
6. [Кастомные стили (JSON)](styles.md) — оверлей полей и стилей абзацев
7. [Промпты для ИИ](prompts.md) — генерация `.md`, расширение промпта схемами
Исходный код конвертера: [`md2gost/`](../md2gost/). Примеры: [`examples/`](../examples/).
В GUI: **Справка → Документация** — тот же набор страниц (вшит в exe).
docs/cli-gui.md
+58
View File
@@ -0,0 +1,58 @@
# CLI и GUI
Движок один: GUI собирает те же параметры, что и аргументы `python -m md2gost`.
## Основные команды
```bash
python -m md2gost # GUI
python -m md2gost --gui report.md
python -m md2gost report.md -o out.docx --type coursework --check --strict
python -m md2gost report.docx --check-pages # только проверка вёрстки готового DOCX
```
Справка: `python -m md2gost -h`.
## Соответствие флагов и GUI
| CLI | Где в GUI | Смысл |
|-----|-----------|--------|
| `--type` | Основные → тип | practice, coursework, vkr, PIS_custom, APID_coursework |
| `-o` / `--output` | Выходной DOCX | путь результата |
| `--heading-numbering` | Основные | `manual` (цифры в md) / `auto` (Word) |
| `--toc` | Основные | `native` (поле Word) / `manual` (собирает md2gost) |
| `--emdash-to-hyphen` | Галочка «—» → «-» | по умолчанию выкл. |
| `--hr-pagebreak` | Галочка --- → разрыв | по умолчанию `---` игнорируется |
| `--title` / `--assignment` / `-t` | Настройки → Файлы | титул, задание, шаблон |
| `--check` / `--check-only` / `--strict` | Галочки проверки ТЗ | замечания по структуре и источникам |
| `--check-pages` | Проверить вёрстку в Word | эвристика полупустых страниц (Word + pywin32) |
| `--table-continuation` | Основные | `word` (по умолчанию), `off`, `legacy`, `caption`, `soft` |
| `--listing-continuation` | Основные | то же для листингов |
| `--table-repeat-header` | Галочка | шапка на фрагментах после word-split |
| `--plantuml-jar` / `--kroki-url` | Настройки → Диаграммы | локальный рендер |
| `--diagram-fallback` | Диаграммы | `remote` / `local` / `off` |
| `--diagram-format` | Диаграммы | `png` / `svg` |
| `--diagram-scale` | Диаграммы | качество PNG PlantUML (по умолчанию 2) |
| `--schemes` | файл схем / Шаблоны UML | путь к `md2gost.schemes.json` |
| `--styles` | Настройки → Файлы → Стили JSON | оверлей `md2gost.styles.json` (также рядом с `.md`); см. [styles.md](styles.md) |
| `--syntax-highlighting` | (CLI) | подсветка в листингах |
| `--debug` | меню Дебаг | отладочные данные в документе (на одну сборку в GUI) |
## Продолжение таблиц и листингов
DOCX не умеет сам писать «Продолжение Таблицы N» только со 2-й страницы. Режим **`word`** (по умолчанию): после сохранения Word COM режет по реальной пагинации. Нужны Windows + Word + pywin32. Без Word: `--table-continuation off` (и то же для листингов).
## Меню GUI
- **Настройки → Файлы** — шаблон, титул, задание, стили JSON, выходной путь
- **Настройки → Диаграммы** — PlantUML, Kroki, формат, кэш includes
- **Шаблоны UML** — редактор `md2gost.schemes.json`
- **Справка → Инструкция / Документация / Схемы / Промпт для ИИ**
(Документация — встроенный просмотр `docs/*.md`, вшито в exe)
## Другие форматы
```bash
python -m md2fodt report.md -o report.fodt # LibreOffice
# PDF через LaTeX — см. md2latex/
```
docs/markdown.md
+153
View File
@@ -0,0 +1,153 @@
# Синтаксис Markdown (диалект md2gost)
Обычный Markdown описывает структуру текста. Для отчёта по ГОСТ нужны ещё: спецразделы без номера, подписи объектов, перекрёстные ссылки, библиография в заданном виде. **md2gost** расширяет MD ровно этими элементами; конвертер сам нумерует рисунки/таблицы/листинги и оформляет DOCX.
## Что совпадает с обычным MD
- Заголовки `#` … `######`
- Абзацы, **жирный**, *курсив*
- Маркированные и нумерованные списки
- Таблицы `| … |`
- Картинки `![alt](path.png)`
- Блоки кода в ограде ` ```язык `
- Формулы `$$ … $$` (и инлайн `$…$` где поддерживается)
## Зачем расширения
| Задача | Обычный MD | md2gost |
|--------|------------|---------|
| Введение без номера «1» | `# Введение` → станет разделом 1 | `# *ВВЕДЕНИЕ` |
| Подпись «Рисунок 1.1 — …» | руками / HTML | `%id` или title у картинки |
| «см. рис. 2» в тексте | нет семантики | `@Рисунок:id` |
| UML → картинка в Word | экспорт PNG вручную | fence `` ```uml `` / схема → Рисунок |
## Спецразделы
Звёздочка `*` = без автоматической нумерации раздела. Текст — ПРОПИСНЫМИ:
```markdown
# *СОДЕРЖАНИЕ
[TOC]
# *ВВЕДЕНИЕ
# 1 Название первого раздела
## 1.1 Подраздел
# *ЗАКЛЮЧЕНИЕ
# *СПИСОК ИСПОЛЬЗОВАННЫХ ИСТОЧНИКОВ
# *ПРИЛОЖЕНИЯ
```
- После `# *СОДЕРЖАНИЕ` обязателен `[TOC]`.
- В конце названия заголовка точку не ставить.
- Для `PIS_custom` структура другая (практические работы) — см. [types.md](types.md).
## Рисунок (файл)
```markdown
Текст со ссылкой на @Рисунок:arch.
![описание](images/arch.png "%arch Название рисунка")
```
В тексте пишите **«Рисунок»**, не «рис.» / «рис».
## Таблица
```markdown
См. @Таблица:cmp.
%cmp Название таблицы
| A | B |
|---|---|
| 1 | 2 |
```
Склеивание ячеек:
- `^` — rowspan (продолжение ячейки сверху)
- `>` — colspan (продолжение слева)
Не ставить `^`/`>` в заголовочной строке; `>` — не в первом столбце. Графу «№ п/п» не добавлять.
## Листинг
~~~markdown
Фрагмент в @Листинг:code1.
%code1 Название листинга
```python
def f():
return 1
```
~~~
## Диаграмма → Рисунок
Перед блоком — `%id Подпись`. Языки: `uml`, `plantuml`, `mermaid`/`mmd`, или id схемы (`c4`, `bpmn`, …).
- `+listing` — ещё и Листинг с исходником
- `+landscape` — альбомная страница под широкий рисунок/таблицу
Подробности: [schemes.md](schemes.md).
## Формула
```markdown
%eq1
$$
E = mc^2
$$
Зависимость (@Формула:eq1) используется далее.
```
Нумеруются **только** формулы, на которые есть `@Формула:…`.
## Ссылки на объекты
`@Рисунок:id`, `@Таблица:id`, `@Листинг:id`, `@Формула:id` — id совпадает с меткой после `%` или в title картинки.
## Источники
В тексте: `[1]`, `[2, 3]` (для ВКР — `[1.5]`).
В списке:
```markdown
[1]: Иванов И. И. Название. — М.: Наука, 2024. — 120 с.
```
Во **ВВЕДЕНИИ** и **ЗАКЛЮЧЕНИИ** ссылок `[n]` быть не должно.
## Приложения
```markdown
# *ПРИЛОЖЕНИЯ
## Приложение А Листинг модуля
…
## Приложение Б Графический материал
```
Буквы: А, Б, В, Г, Д, Е, Ж, И, К… **Нельзя:** Ё, З, Й, О, Ч, Ь, Ы, Ъ.
## Тире и разрыв страницы
- Тире в предложениях: «—» (по умолчанию сохраняется). Замена на «-»: `--emdash-to-hyphen`.
- Строка `---` / `***` / `___` по умолчанию **игнорируется**. Разрыв страницы: `--hr-pagebreak` или галочка в GUI.
## Запрещено в отчёте
- «рис.», «табл.»
- графа «№ п/п»
- сноски `[^1]`
- формулы обычным текстом вместо `$$…$$`
- нумерация спецразделов (`# ВВЕДЕНИЕ` вместо `# *ВВЕДЕНИЕ`)
docs/prompts.md
+33
View File
@@ -0,0 +1,33 @@
# Промпты для ИИ
Промпты лежат в [`prompts/`](../prompts/). В GUI: **Справка → Промпт для ИИ** — выбрать, при необходимости **дописать схемы**, скопировать в буфер. Полная документация также доступна в **Справка → Документация** (вшита в exe).
## Какие файлы
| Файл | Когда |
|------|--------|
| [`generate-md.md`](../prompts/generate-md.md) | Базовый: диалект md2gost, чем отличается от обычного MD; UML/Mermaid рисует конвертер |
| [`generate-mirea-report.md`](../prompts/generate-mirea-report.md) | Полный отчёт ГОСТ / МИРЭА (`coursework`, `practice`, `vkr`) |
| [`generate-pis-custom-report.md`](../prompts/generate-pis-custom-report.md) | Итоговый отчёт ПИС (`PIS_custom`) |
## Как пользоваться
1. Откройте промпт (файл или GUI).
2. В GUI включите нужные схемы (C4, BPMN, …) — в конец промпта добавятся макросы и `ai-prompt` из `md2gost.schemes.json`.
3. Скопируйте собранный текст в ChatGPT / Claude / Cursor / Copilot.
4. Следующим сообщением: тип работы, тема, черновик / требования.
5. Сохраните ответ как `.md` и конвертируйте:
```bash
python -m md2gost report.md -o report.docx --type coursework --check --strict
```
## Зачем кнопки схем
Базовый промпт уже говорит: блоки `` ```uml `` / `` ```mermaid `` / `` ```uml-c4 `` конвертер сам превратит в Рисунок. Кнопки нужны, когда модели надо знать **конкретные макросы** выбранной схемы (Person/Rel для C4, Start/XOR/Flow для BPMN и т.д.) — в том числе пользовательских из «Шаблоны UML».
## Подробнее о синтаксисе
- [markdown.md](markdown.md)
- [schemes.md](schemes.md)
- [prompts/README.md](../prompts/README.md)
docs/quickstart.md
+61
View File
@@ -0,0 +1,61 @@
# Быстрый старт
## Установка
Нужен Python 3.10+.
```bash
pip install -e .
# или
poetry install
```
Для продолжения таблиц/листингов через Word COM (режим `word` по умолчанию) на Windows:
```bash
pip install pywin32
```
Нужны установленный Microsoft Word.
## Запуск
```bash
python -m md2gost # GUI без файла
python -m md2gost --gui
python -m md2gost report.md -o report.docx --type coursework --check
md2gost-gui # то же GUI (entry point)
```
### Windows exe
В корне репозитория: `build-exe.bat` → `dist\md2gost.exe`.
- Двойной клик — GUI.
- CLI: `md2gost.exe report.md -o report.docx --type coursework`.
## GUI за минуту
1. Перетащите `.md` в верхнюю область (или кликните по ней).
2. Выберите тип документа (`practice` по умолчанию).
3. При необходимости: Настройки → Файлы (титул, задание), Настройки → Диаграммы, меню «Шаблоны UML».
4. Нажмите «Конвертировать».
Справка в меню: **Инструкция**, **Схемы**, **Промпт для ИИ**.
## Типы документов (кратко)
| `--type` | Назначение |
|----------|------------|
| `practice` / `coursework` | Практика / курсовая по ТЗ МИРЭА |
| `vkr` | ВКР (раздельный список, графическое приложение) |
| `PIS_custom` | Итоговый отчёт по практическим работам |
| `APID_coursework` | Курсовая «Архитектура приложений и данных» |
Подробнее: [types.md](types.md).
## Следующие шаги
- Написать отчёт в диалекте md2gost: [markdown.md](markdown.md)
- Вставить диаграммы: [schemes.md](schemes.md)
- Сгенерировать `.md` через ИИ: [prompts.md](prompts.md)
docs/schemes.md
+121
View File
@@ -0,0 +1,121 @@
# Схемы и диаграммы
В отчёте блок кода с языком диаграммы превращается в **Рисунок** (PNG или SVG). PNG руками экспортировать не нужно: md2gost вызывает PlantUML (jar / Kroki) или Kroki для Mermaid.
## Синтаксис в markdown
````markdown
%usecase1 Диаграмма прецедентов +listing
```uml
@startuml
actor Student
Student --> (Login)
@enduml
```
````
Широкая схема:
````markdown
%arch1 Архитектура +landscape
```uml-c4
Person(user, "Студент")
System(app, "Портал")
Rel(user, app, "логин")
```
````
| Оградка | Что происходит |
|---------|----------------|
| `` ```uml `` / `` ```plantuml `` | Сырой PlantUML (`@startuml`…`@enduml`) |
| `` ```uml-<id> `` / `` ```<id> `` | Схема из `md2gost.schemes.json` (обёртка и `!include` добавляются сами) |
| `` ```mermaid `` / `` ```mmd `` | Mermaid через Kroki |
| `` ```bpmn `` / `` ```uml-bpmn `` | BPMN 2.0 (макросы библиотеки md2gost) |
**IDEF0 / DFD** конвертер не рисует — вставляйте готовый PNG как обычный Рисунок.
## Встроенные схемы
Файл шаблона: [`md2gost/diagrams/schemes.json`](../md2gost/diagrams/schemes.json). При первом запуске копируется в `md2gost.schemes.json` рядом с приложением (существующий файл не перезаписывается).
| id | Название | Оградка |
|----|----------|---------|
| `c4` | C4 Container | `` ```uml-c4 `` / `` ```c4 `` |
| `c4context` | C4 Context | `` ```uml-c4context `` |
| `c4component` | C4 Component | `` ```uml-c4component `` |
| `usecase` | Прецеденты | `` ```uml-usecase `` / `` ```usecase `` |
| `bpmn` | BPMN 2.0 | `` ```bpmn `` / `` ```uml-bpmn `` |
Для схем в теле пишите **только макросы** (Person, Start, XOR, …) — без `@startuml` и без `!include`, если схема сама их добавляет.
### C4 (пример макросов)
`Person`, `System`, `System_Ext`, `Container`, `ContainerDb`, `Rel` / `Rel_R`…
### Use Case
`actor`, `usecase`, связи `-->`, `<<include>>`, `<<extend>>`.
### BPMN
`Pool` / `Lane`, `Start` / `StartMessage` / `End`, `UserTask` / `ServiceTask`, `XOR` / `AND` / `OR`, `Flow` / `CondFlow` / `DefaultFlow` / `MessageFlow`, …
Sequence Flow только внутри пула; между пулами — `MessageFlow`.
Полные шпаргалки — поля `docs` и `ai-prompt` в JSON; в GUI: **Шаблоны UML** и кнопки схем в **Справка → Промпт для ИИ**.
## Файл схем: поля
```json
{
"c4": {
"title": "C4 Container",
"docs": "…макросы…",
"ai-prompt": "…инструкция для ИИ…",
"includes": ["https://…/C4_Container.puml"],
"prefix": "@startuml\n",
"postfix": "\nLAYOUT_WITH_LEGEND()\n@enduml"
}
}
```
| Поле | Назначение |
|------|------------|
| `title` | Подпись в GUI |
| `docs` | Шпаргалка макросов |
| `ai-prompt` | Фрагмент для промпта ИИ |
| `includes` | Локальные `.puml` или URL |
| `prefix` / `postfix` | Обёртка вокруг тела |
| `theme` | опционально `!theme …` |
id схемы: латиница, цифры, `_`; начинается с буквы.
## Слои загрузки (позже побеждает)
1. Встроенный шаблон `md2gost/diagrams/schemes.json`
2. Пользовательский файл рядом с приложением (`md2gost.schemes.json`)
3. `md2gost.schemes.json` рядом с `.md`
4. Явный путь `--schemes path.json`
## Рендер
**UML / схемы:**
1. Java + `plantuml.jar` (вшитый / `%LOCALAPPDATA%\md2gost\` / `--plantuml-jar`)
2. Локальный Kroki (`KROKI_URL` / `--kroki-url`, по умолчанию `http://localhost:8000`)
3. `https://kroki.io` при `--diagram-fallback remote` (по умолчанию)
**Mermaid** — только Kroki (шаги 2–3).
Формат: `--diagram-format png` (по умолчанию) или `svg`. Масштаб рендера PlantUML: `--diagram-scale` (по умолчанию 2 — качество, размер на странице как при 1).
Кэш картинок: `{каталог_md}/.md2gost-cache/`.
Кэш includes: `md2gost.include-cache.json` + папка `include-cache/` (сброс в GUI: Настройки → Диаграммы / Шаблоны UML).
## Свои схемы
1. Меню **Шаблоны UML** — добавить / править / сохранить.
2. Или править `md2gost.schemes.json` вручную («Открыть JSON»).
3. CLI: `--schemes путь.json`.
docs/styles.md
+67
View File
@@ -0,0 +1,67 @@
# Кастомные стили (JSON)
Опциональный оверлей оформления поверх пресета `--type` (`mirea` или `pis_custom`).
Неуказанные поля остаются у пресета. Стили пишет конвертер в DOCX сам — вручную в шаблон добавлять не нужно.
## Как подключить
Позже побеждает (deep-merge только указанных ключей):
1. Встроенный пресет типа документа
2. `md2gost.styles.json` рядом с `.md` (если есть)
3. `--styles путь.json` или путь в GUI: **Настройки → Файлы → Стили JSON**
Файл рядом с exe при первом запуске **не создаётся**.
```bash
python -m md2gost report.md -o report.docx --type practice --styles examples/md2gost.styles.json
```
Пример: [`examples/md2gost.styles.json`](../examples/md2gost.styles.json).
## Схема
Два блока. Неизвестный ключ или имя стиля — ошибка.
```json
{
"page": {
"left_mm": 30,
"right_mm": 10,
"top_mm": 20,
"bottom_mm": 20
},
"styles": {
"Heading 1": {
"alignment": "center",
"size_pt": 14,
"all_caps": true
}
}
}
```
### `page`
| Ключ | Единица | Смысл |
|------|---------|--------|
| `left_mm` / `right_mm` / `top_mm` / `bottom_mm` | мм | Поля страницы |
### Имена стилей
`Normal`, `Heading 1`, `Heading 2`, `Heading 3`, `Caption Figure`, `Caption Table`, `Название таблицы`, `Caption Listing`, `Caption`, `Code`, `Table Text`, `Bibliography`, `Bibliography Heading`, `toc 1`, `toc 2`, `toc 3`, `Footer`, `Hyperlink`, `FollowedHyperlink`, `Space After Table`.
### Поля стиля
| Ключ | Тип / значения |
|------|----------------|
| `font_name` | строка |
| `size_pt` | число (pt) |
| `bold`, `italic`, `all_caps`, `underline` | bool |
| `alignment` | `left` \| `center` \| `justify` |
| `first_line_indent_cm`, `left_indent_cm`, `right_indent_cm` | см |
| `space_before_mm`, `space_after_mm` | мм |
| `line_spacing` | `1.0` \| `1.5` |
| `page_break_before`, `keep_with_next`, `widow_control` | bool |
Не в JSON: табы оглавления (считаются от ширины полосы), отступы списков, формулы из шаблона, цвет (всегда чёрный).
docs/types.md
+66
View File
@@ -0,0 +1,66 @@
# Типы документов
Задаётся флагом `--type` / выбором в GUI. Профили: [`md2gost/profiles.py`](../md2gost/profiles.py).
## Сводка
| Тип | Стили | Нумерация объектов | Источники | Структура |
|-----|--------|-------------------|-----------|-----------|
| `practice` | МИРЭА | по разделам (1.1, 2.1) | 5–7, ≤5 лет | Введение, разделы, заключение, список, приложения |
| `coursework` | МИРЭА | по разделам | 5–7, ≤5 лет | то же |
| `vkr` | МИРЭА | по разделам | ≥10 в **каждом** разделе списка, ≤5 лет | + приложение «Графический материал»; ссылки `[1.5]` |
| `PIS_custom` | ПИС | сквозная (1, 2, 3) | не требуются | H1 = практические работы; без введения/заключения по умолчанию |
| `APID_coursework` | МИРЭА | по разделам | 7–20, ≤5 лет | обязательные главы/пункты АПИД (см. ниже) |
## coursework / practice
Спецразделы с `*`, нумерованная основная часть. В DOCX: H1 слева с отступом (кроме СОДЕРЖАНИЕ / СПИСОК — по центру).
Проверка: `--check` / `--strict`.
## vkr
- Список источников **с разделами**; в каждом ≥10 записей.
- Ссылки вида `[1.5]`, при цитировании `[2.18, c. 21-25]`.
- Обязательное приложение с текстом «Графический материал» в названии.
## PIS_custom
Итоговый отчёт по практическим работам.
```markdown
# *СОДЕРЖАНИЕ
[TOC]
# Практическая работа №1. Название работы
## Цель работы
## Ход работы
## Выводы
# Практическая работа №2. …
```
- H1 **без** `*` (кроме СОДЕРЖАНИЕ): в DOCX — ПРОПИСНЫМИ по центру.
- H2 с абзацным отступом.
- Титул («Отчёт по практическим работам …») — отдельный DOCX: `--title title.docx`.
Пример: [`examples/pis_custom.md`](../examples/pis_custom.md).
Промпт: [`prompts/generate-pis-custom-report.md`](../prompts/generate-pis-custom-report.md).
## APID_coursework
Курсовая «Архитектура приложений и данных» (методичка Аншиной/Лагуновой). Оформление как у `coursework`, плюс проверка заголовков:
1. Теоретические аспекты …
2. Прикладные аспекты …
- 2.1 Описание проекта …
- 2.2 Описание роли …
- 2.3 Описание архитектуры …
- 2.4 Варианты развития архитектуры …
Источники: 7–20.
```bash
python -m md2gost report.md -o report.docx --type APID_coursework --check --title title.docx --assignment assignment.docx
```