S.Gromov
b3d501c920
- Добавлен триггер dev в CI со сборочным job (generate + docs:build + build) - Убраны устаревшие шаги: npm run docs, коммит generated/, README_RU.md - Прод-пайплайн: build → version (тег) → docker → deploy - CONTRIBUTING.md переписан под текущую структуру проекта
122 lines
5.5 KiB
Markdown
122 lines
5.5 KiB
Markdown
# Правила работы над документацией
|
||
|
||
Мета-документ: как устроен проект, как писать и редактировать разделы.
|
||
|
||
## О проекте
|
||
|
||
Сайт-документация архитектуры SLM Design с лендингом.
|
||
|
||
- Лендинг: React + Vite
|
||
- Документация: VitePress
|
||
- Язык: русский
|
||
- Документация: `docs/architecture/`
|
||
|
||
## Команды
|
||
|
||
| Команда | Что делает |
|
||
|---------|-----------|
|
||
| `npm run dev` | Локальный сервер лендинга |
|
||
| `npm run build` | Сборка лендинга |
|
||
| `npm run docs:dev` | Локальный сервер документации |
|
||
| `npm run docs:build` | Сборка документации |
|
||
| `npm run generate` | Генерация артефактов (llms.txt, llms-full.txt, ARCHITECTURE.md, ZIP, README) |
|
||
|
||
## Структура файлов
|
||
|
||
```
|
||
docs/
|
||
├── index.md # Страница навигации по документации
|
||
└── architecture/ # Разделы архитектуры
|
||
├── index.md # Обзор SLM Design
|
||
├── layers.md # Слои
|
||
├── modules.md # Модули
|
||
└── segments.md # Сегменты
|
||
.vitepress/
|
||
├── config.ts # Конфигурация VitePress, сайдбар
|
||
public/
|
||
├── llms.txt # Карта документации для LLM
|
||
├── llms-full.txt # Полная документация в одном файле
|
||
└── ARCHITECTURE.md # Единый файл архитектуры
|
||
generate.ts # Скрипт генерации артефактов
|
||
src/ # Исходники лендинга (React + Vite)
|
||
```
|
||
|
||
### Добавление нового раздела
|
||
|
||
1. Создать `.md`-файл в `docs/architecture/`.
|
||
2. Добавить пункт в сайдбар — `.vitepress/config.ts`.
|
||
3. Добавить `description` в frontmatter файла — используется для `llms.txt`.
|
||
4. Запустить `npm run generate` для обновления артефактов.
|
||
|
||
## Frontmatter
|
||
|
||
Каждый `.md`-файл начинается с YAML frontmatter:
|
||
|
||
```yaml
|
||
---
|
||
title: Название раздела
|
||
description: Краткое описание для llms.txt
|
||
---
|
||
```
|
||
|
||
- `title` — совпадает с `h1`-заголовком в файле.
|
||
- `description` — кратное описание содержимого страницы, используется при генерации `llms.txt`.
|
||
|
||
## Структура страницы документации
|
||
|
||
Каждая страница начинается одинаково:
|
||
|
||
1. **Заголовок** (`h1`) — совпадает с `title` из frontmatter.
|
||
2. **Описание раздела** — 1–2 строки сразу после заголовка. Говорит, что это за раздел, какую информацию он описывает и что читатель в нём получит.
|
||
3. **Определение** (`## Определение`) — для справочных страниц, посвящённых одному термину. Короткая формулировка жирным: что это за сущность и какую роль она играет.
|
||
4. **Контент** — остальные `h2`-подразделы.
|
||
|
||
## Конвенции оформления
|
||
|
||
### Заголовки
|
||
|
||
- Один `h1` на файл — совпадает с `title` из frontmatter.
|
||
- Сразу после `h1` — описание раздела (1–2 предложения).
|
||
- Основные секции — `h2`.
|
||
- Подсекции внутри `h2` — `h3`.
|
||
- `h4` не используется.
|
||
|
||
### Примеры кода
|
||
|
||
- Блоки кода с указанием языка: ` ```tsx `, ` ```css `, ` ```bash `, ` ```text `.
|
||
- Путь к файлу указывается перед блоком кода текстом или комментарием внутри блока.
|
||
- Дерево файлов — ` ```text ` с символами `├──`, `└──`, `│`.
|
||
|
||
### Блоки «Хорошо / Плохо»
|
||
|
||
Используются для контрастного сравнения правильного и неправильного подхода.
|
||
|
||
```markdown
|
||
**Хорошо:**
|
||
|
||
\`\`\`tsx
|
||
// правильный код
|
||
\`\`\`
|
||
|
||
**Плохо:**
|
||
|
||
\`\`\`tsx
|
||
// неправильный код
|
||
\`\`\`
|
||
```
|
||
|
||
### Таблицы
|
||
|
||
Используются для структурированных перечислений: настройки, команды, соответствия.
|
||
Формат — стандартный Markdown: `| Ключ | Описание |`.
|
||
|
||
### Ссылки между разделами
|
||
|
||
Раздел может ссылаться на другие разделы, но не дублирует их содержимое.
|
||
|
||
## Принципы
|
||
|
||
1. **Не дублировать.** Одна мысль живёт в одном месте. Остальные ссылаются.
|
||
2. **Пустые секции не создавать.** Если для раздела нет специфики — секция не создаётся.
|
||
3. **Примеры обязательны.** Раздел без примеров кода — незавершён.
|