---
icon: material/book-cog-outline
---

# :material-book-cog-outline: Сборка документации

## Стилистика и правила оформления

Все исходники хранятся в директории `src/` в формате **Markdown** (формат файлов `.md`).

Структура проекта и его конфигурация описываются в файле `mkdocs.yml` в корне репозитория.

Структура исходных файлов документации и содержание должны быть согласованными.

Все ссылки на соседние страницы и изображения должны быть относительными.

**Каждое предложение должно быть на одной строке.**
Это даёт более наглядную разницу (diff) в тексте при работе с git.

Абзацы и списки должны отделяться 1 пустой строкой сверху и снизу.

Допустимо использовать любые стилистические возможности темы **Material for MkDocs** и самого **mkdocs**, но не следует визуально перегружать текст.
Документацию по ним см. по ссылкам ниже.

## Добавление изображений

**Все изображения хранятся только в директории `src/assets/img/` и вложенных в неё.**

Общая суть такова:

* чем больше размеры, тем хуже должно быть качество;
* чем меньше размеры, тем чётче должен быть текст.

Каждое изображение должно:

* быть сохранено в формате jpg;
* иметь размер неболее 150 Кб;
* быть сжатым с качеством 65-80% от исходного;
* быть размером до 1500 px по наибольшей стороне.

Если на изображении есть текст, он должен оставаться различимым и читаемым.

Но если на изображении есть любые конфиденциальные данные и его невозможно кадрировать без потери смысла, то их необходимо скрыть.

Хорошей практикой будет использовать спойлеры для скрытия больших и/или идущих подряд нескольких изображений, например:

```
Совершенно любой текст, lorem ipsum dolor sit amet.
Совершенно любой текст, lorem ipsum dolor sit amet.

??? quote "В этом спойлере несколько больших картинок"
    ![Подпись-плейсхолдер1](../assets/img/example1.jpg)
    ![Подпись-плейсхолдер2](../assets/img/example2.jpg)

Продолжение текста, 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](https://localhost:3000) для просмотра изменений в реальном времени.

## Генерация статических файлов

```
make build
```

Генерирует статические файлы, которую можно версионировать и хранить/деплоить отдельно.

Открывает [localhost:8080/docs](https://localhost:8080/docs) для просмотра сгенерированной документации.

Готовый скомпилированный статический сайт с документацией находится в директории `site/`.
Он же хранится в репозитории вместе с исходными файлами, потому что:

* я посчитал это **более удобным для деплоя**: ради редких обновлений нет смысла тратить ресурсы серверов на ci/cd, actions по хукам и перманентную работу `mkdocs` в режиме `build`;
* я посчитал это **более удобным для использования**: можно в любой момент открыть актуальную документацию в браузере через `site/index.html` без необходимости `make` и `docker`.

Пересборка должна происходить перед каждым коммитом.