Сборка документации¶

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

Все исходники хранятся в директории 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
• mkdocs
• 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 для просмотра изменений в реальном времени.

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

make build

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

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

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

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

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