- update документация - промт для ии полу конфигурируемый
This commit is contained in:
Igor20264
@@ -1,209 +1,34 @@
|
||||
# GhostEditor
|
||||
Программа для конвертации из формата `md` в формат `docx`(x это без макросов, m с макросами) (`Office Open XML`),`odt`(`OpenDocument`)
|
||||
# GhostEditor / md2gost
|
||||
|
||||
#### **1. python-docx**
|
||||
**Назначение**: Создание и модификация Word-документов.
|
||||
**Ключевые возможности**:
|
||||
- Добавление/редактирование текста, таблиц, изображений.
|
||||
- Управление стилями, колонтитулами, сносками.
|
||||
- Работа с XML через абстракции (Paragraph, Run, Table).
|
||||
Конвертер **Markdown → DOCX** по методическим указаниям РТУ МИРЭА (ГОСТ 7.32-2017) и профилям ПИС / АПИД. Есть GUI, CLI и промпты для генерации `.md` через ИИ.
|
||||
|
||||
**Пример**:
|
||||
```python
|
||||
from docx import Document
|
||||
from docx.shared import Pt
|
||||
## Быстрый старт
|
||||
|
||||
doc = Document()
|
||||
paragraph = doc.add_paragraph("Hello ")
|
||||
run = paragraph.add_run("OOXML!")
|
||||
run.bold = True
|
||||
run.font.size = Pt(14)
|
||||
|
||||
# Таблица
|
||||
table = doc.add_table(rows=2, cols=2)
|
||||
table.cell(0, 0).text = "Cell A1"
|
||||
|
||||
doc.save("report.docx")
|
||||
```bash
|
||||
pip install -e .
|
||||
python -m md2gost # GUI
|
||||
python -m md2gost report.md -o report.docx --type coursework --check
|
||||
```
|
||||
|
||||
**Плюсы**:
|
||||
- Интуитивный API, близкий к логике Word.
|
||||
- Поддержка всех ключевых частей пакета (headers, footers, styles).
|
||||
Windows: `build-exe.bat` → `dist\md2gost.exe` (двойной клик — GUI).
|
||||
|
||||
**Минусы**:
|
||||
- Нет поддержки макросов.
|
||||
- Ограниченная работа с графикой (изображения добавляются, но редактирование сложно).
|
||||
## Документация
|
||||
|
||||
**Ссылка**: [python-docx.readthedocs.io](https://python-docx.readthedocs.io/)
|
||||
Полное описание — в [`docs/`](docs/):
|
||||
|
||||
---
|
||||
| Раздел | Содержание |
|
||||
|--------|------------|
|
||||
| [Быстрый старт](docs/quickstart.md) | Установка, GUI, типы документов |
|
||||
| [Синтаксис Markdown](docs/markdown.md) | Диалект md2gost vs обычный MD |
|
||||
| [Схемы и диаграммы](docs/schemes.md) | PlantUML, Mermaid, `md2gost.schemes.json` |
|
||||
| [Типы работ](docs/types.md) | coursework, practice, vkr, PIS, APID |
|
||||
| [CLI и GUI](docs/cli-gui.md) | Флаги и где они в окне |
|
||||
| [Промпты для ИИ](docs/prompts.md) | Генерация MD, кнопки схем в GUI |
|
||||
|
||||
#### **2. docxtpl**
|
||||
**Назначение**: Генерация документов по шаблонам (Jinja2).
|
||||
**Особенности**:
|
||||
- Шаблоны .docx с переменными (`{{ variable }}`) и логикой (`{% if %}`).
|
||||
- Поддержка таблиц, изображений, HTML-фрагментов.
|
||||
Краткая справка по пакету: [`md2gost/README.md`](md2gost/README.md).
|
||||
Промпты: [`prompts/`](prompts/).
|
||||
|
||||
**Пример**:
|
||||
```python
|
||||
from docxtpl import DocxTemplate
|
||||
## Связанные форматы
|
||||
|
||||
doc = DocxTemplate("template.docx")
|
||||
context = {
|
||||
"title": "Отчет за 2023",
|
||||
"items": [{"name": "Item 1"}, {"name": "Item 2"}]
|
||||
}
|
||||
doc.render(context)
|
||||
doc.save("output.docx")
|
||||
```
|
||||
|
||||
**Плюсы**:
|
||||
- Идеален для шаблонизированных отчетов (договоры, счета).
|
||||
- Интеграция с Django/Flask.
|
||||
|
||||
**Минусы**:
|
||||
- Требует предварительной настройки шаблонов в Word.
|
||||
|
||||
**Ссылка**: [github.com/elapouya/python-docx-template](https://github.com/elapouya/python-docx-template)
|
||||
|
||||
---
|
||||
|
||||
#### **3. mammoth**
|
||||
**Назначение**: Конвертация .docx → HTML с сохранением структуры.
|
||||
**Особенности**:
|
||||
- Преобразует стили Word в CSS-классы.
|
||||
- Подходит для извлечения контента из сложных документов.
|
||||
|
||||
**Пример**:
|
||||
```python
|
||||
import mammoth
|
||||
|
||||
with open("document.docx", "rb") as docx_file:
|
||||
result = mammoth.convert_to_html(docx_file)
|
||||
html = result.value # HTML-строка
|
||||
warnings = result.messages # Предупреждения
|
||||
```
|
||||
|
||||
**Плюсы**:
|
||||
- Сохраняет семантику (заголовки, списки, таблицы).
|
||||
- Легко интегрируется с парсерами (BeautifulSoup).
|
||||
|
||||
**Минусы**:
|
||||
- Не подходит для обратной конвертации (HTML → docx).
|
||||
|
||||
**Ссылка**: [github.com/mwilliamson/mammoth.py](https://github.com/mwilliamson/mammoth.py)
|
||||
|
||||
---
|
||||
|
||||
### **Низкоуровневые инструменты (для кастомных задач)**
|
||||
|
||||
#### **1. zipfile + lxml**
|
||||
**Назначение**: Прямой доступ к XML-структуре OOXML.
|
||||
**Когда использовать**:
|
||||
- При работе с нестандартными частями пакета (напр., кастомные XML-маппинги в Excel).
|
||||
- Для восстановления поврежденных файлов.
|
||||
|
||||
**Пример для Excel**:
|
||||
```python
|
||||
import zipfile
|
||||
from lxml import etree
|
||||
|
||||
# Распаковываем workbook.xml
|
||||
with zipfile.ZipFile("report.xlsx") as xlsx:
|
||||
xml_data = xlsx.read("xl/workbook.xml")
|
||||
|
||||
# Парсим XML
|
||||
workbook = etree.fromstring(xml_data)
|
||||
namespaces = {"ns": "http://schemas.../spreadsheetml/2006/main"}
|
||||
sheets = workbook.findall(".//ns:sheet", namespaces)
|
||||
|
||||
# Меняем имя листа
|
||||
sheets[0].set("{http://.../officeDocument/2006/relationships}name", "New Sheet")
|
||||
|
||||
# Сохраняем изменения
|
||||
with zipfile.ZipFile("fixed.xlsx", "w") as new_xlsx:
|
||||
for file in xlsx.namelist():
|
||||
if file != "xl/workbook.xml":
|
||||
new_xlsx.writestr(file, xlsx.read(file))
|
||||
new_xlsx.writestr("xl/workbook.xml", etree.tostring(workbook))
|
||||
```
|
||||
|
||||
**Плюсы**:
|
||||
- Полный контроль над структурой.
|
||||
- Работает с любыми частями пакета.
|
||||
|
||||
**Минусы**:
|
||||
- Требует знания XML-схем OOXML.
|
||||
- Риск повреждения файла при ошибках.
|
||||
|
||||
---
|
||||
|
||||
#### **2. officedoc**
|
||||
**Назначение**: Универсальный доступ к форматам Office (docx, xlsx, pptx).
|
||||
**Особенности**:
|
||||
- Объединяет функционал `python-docx`, `openpyxl`, `python-pptx` в едином API.
|
||||
- Упрощает обработку мультимедийных вложений.
|
||||
|
||||
**Пример**:
|
||||
```python
|
||||
from officedoc import Document
|
||||
|
||||
doc = Document("mixed.docx")
|
||||
for image in doc.images:
|
||||
image.save("extracted_" + image.filename)
|
||||
|
||||
for table in doc.tables:
|
||||
print(table.to_dataframe()) # Конвертация в pandas DataFrame
|
||||
```
|
||||
|
||||
**Ссылка**: [github.com/mikem1701/officedoc](https://github.com/mikem1701/officedoc)
|
||||
|
||||
---
|
||||
|
||||
### **Сравнение библиотек**
|
||||
|
||||
| **Библиотека** | **Скорость** | **Сложность** | **Особенности** |
|
||||
|----------------------|-------------|---------------|----------------------------|
|
||||
| **python-docx** | Средняя | Средняя | Стандарт для работы с Word |
|
||||
| **docxtpl** | Средняя | Низкая | Шаблонизация через Jinja2 |
|
||||
| **zipfile + lxml** | Высокая | Высокая | Полный контроль над XML |
|
||||
|
||||
---
|
||||
|
||||
#### Для Word (.docx)
|
||||
- **Простое создание документов**: `python-docx`.
|
||||
- **Шаблонные документы** (договоры, счета): `docxtpl`.
|
||||
- **Извлечение контента**: `mammoth` → обработка HTML через BeautifulSoup.
|
||||
- **Редактирование структуры**: `python-docx` + `zipfile` для кастомных частей.
|
||||
|
||||
#### Для кастомных задач
|
||||
- **Восстановление файлов**: `zipfile` + `lxml` (ручное исправление XML).
|
||||
- **Интеграция с внешними системами**: `openpyxl`/`python-docx` + REST API (напр., выгрузка данных из БД в Excel).
|
||||
|
||||
---
|
||||
|
||||
### Типичные проблемы и решения
|
||||
|
||||
2. Стили не применяются в Word
|
||||
- Проблема: `python-docx` использует стили из `styles.xml`, но не создает новые автоматически.
|
||||
- Решение:
|
||||
```python
|
||||
from docx.shared import Pt
|
||||
style = doc.styles.add_style("Heading3", WD_STYLE_TYPE.PARAGRAPH)
|
||||
font = style.font
|
||||
font.name = "Arial"
|
||||
font.size = Pt(12)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### **Заключение**
|
||||
Для 90% задач достаточно:
|
||||
- **Excel**: `openpyxl` или `pandas`.
|
||||
- **Word**: `python-docx` + `docxtpl`.
|
||||
|
||||
**Используйте низкоуровневые методы (zipfile/lxml) только когда**:
|
||||
|
||||
*Для углубленного изучения:*
|
||||
- [Open XML SDK 2.5](https://learn.microsoft.com/ru-ru/office/open-xml/open-xml-sdk) (официальная документация Microsoft).
|
||||
- [ECMA-376 стандарт](https://www.ecma-international.org/publications-and-standards/standards/ecma-376/) (полная спецификация).
|
||||
- FODT (LibreOffice): `python -m md2fodt` — [`md2fodt/`](md2fodt/)
|
||||
- PDF через LaTeX: [`md2latex/`](md2latex/)
|
||||
|
||||
Reference in New Issue
Block a user