104 lines
5.0 KiB
Markdown
104 lines
5.0 KiB
Markdown
---
|
|
icon: material/book-cog-outline
|
|
---
|
|
|
|
# :material-book-cog-outline: Сборка документации
|
|
|
|
## Стилистика и правила оформления
|
|
|
|
Все исходники хранятся в директории `content/` в формате **Markdown** (формат файлов `.md`).
|
|
|
|
Структура проекта и его конфигурация описываются в файле `mkdocs.yml` в корне репозитория.
|
|
|
|
Структура исходных файлов документации и содержание должны быть согласованными.
|
|
|
|
Все ссылки на соседние страницы и изображения должны быть относительными.
|
|
|
|
**Каждое предложение должно быть на одной строке.**
|
|
Это даёт более наглядную разницу (diff) в тексте при работе с git.
|
|
|
|
Абзацы и списки должны отделяться 1 пустой строкой до и после.
|
|
|
|
Допустимо использовать любые стилистические возможности темы **Material for MkDocs** и самого **mkdocs**, но не следует визуально перегружать текст.
|
|
Документацию по ним см. по ссылкам ниже.
|
|
|
|
## Добавление изображений
|
|
|
|
**Все изображения хранятся в директории `_assets/` рядом с документом.**
|
|
|
|
Общая суть такова:
|
|
|
|
* чем больше размеры, тем хуже должно быть качество;
|
|
* чем меньше размеры, тем чётче должен быть текст.
|
|
|
|
Каждое изображение должно:
|
|
|
|
* быть сохранено в формате jpg;
|
|
* иметь размер неболее 150 Кб;
|
|
* быть сжатым с качеством 65-80% от исходного;
|
|
* быть размером до 1500 px по наибольшей стороне.
|
|
|
|
Если на изображении есть текст, он должен оставаться различимым и читаемым.
|
|
|
|
Но если на изображении есть любые конфиденциальные данные и его невозможно кадрировать без потери смысла, то их необходимо скрыть.
|
|
|
|
Хорошей практикой будет использовать спойлеры для скрытия больших и/или идущих подряд нескольких изображений, например:
|
|
|
|
```
|
|
Совершенно любой текст, lorem ipsum dolor sit amet.
|
|
Совершенно любой текст, lorem ipsum dolor sit amet.
|
|
|
|
??? quote "В этом спойлере несколько больших картинок"
|
|
|
|
|
|
|
|
Продолжение текста, lorem ipsum dolor sit amet.
|
|
Продолжение текста, lorem ipsum dolor sit amet.
|
|
```
|
|
|
|
Эти простые правила позволят поддерживать репозиторий достаточно компактным, а страницы делать комфортными для чтения, экономя трафик для мобильных устройств.
|
|
|
|
## Стек
|
|
|
|
* make
|
|
* [docker](https://docker.com)
|
|
* [mkdocs](https://www.mkdocs.org/)
|
|
* [squidfunk/mkdocs-material](https://hub.docker.com/r/squidfunk/mkdocs-material)
|
|
* <https://squidfunk.github.io/mkdocs-material>
|
|
* <https://squidfunk.github.io/mkdocs-material/reference/admonitions/>
|
|
* <https://squidfunk.github.io/mkdocs-material/reference/icons-emojis/>
|
|
|
|
## Запуск mkdocs в контейнере
|
|
|
|
```
|
|
make live
|
|
```
|
|
|
|
Перегенерирует документацию на лету сразу после сохранения файлов.
|
|
|
|
Документацию в реальном времени можно просматривать по адресу [localhost:3000](http://localhost:3000).
|
|
|
|
## Генерация статического сайта
|
|
|
|
```
|
|
make site
|
|
```
|
|
|
|
Генерирует статические файлы, которую можно версионировать, хранить,деплоить отдельно или просматривать на ПК через браузер.
|
|
|
|
Готовый скомпилированный статический сайт с документацией находится в директории `site/`.
|
|
|
|
## Генерация docker-образа
|
|
|
|
```
|
|
make image
|
|
```
|
|
|
|
Собирает docker-образ на основе nginx, генерируя перед этим статический сайт.
|
|
|
|
Запустить контейнер из этого образа по адресу [localhost:3001](http://localhost:3001) можно командой:
|
|
|
|
```
|
|
make run
|
|
```
|