Инструкция по установке

MkDocs

Инструкция по установке есть на сайте MkDocs.

Надо установить:

• python python.org
• pip – менеджер пакет (ставится, обычно, вместе с питоном)
• mkdocs – пакет с движком mkdocs

Полезные ссылки:

• mkdocs.org
• плагины MkDocs
• Темы MkDocs
• markdown дополнения

Тема

В проекте используется тема material.

Для установки запускаем:

pip install mkdocs-material

Полезные ссылки:

• Настройки темы material
• Плагины из темы material
• Проект темы material на GitHub

Плагины

В проекте используются плагины:

• search – встроенный плагин поиска.
• img2fig – отображение картинок в отдельном теге с подписью внизу.

pip install mkdocs-img2fig-plugin
pip install mkdocs-section-index
pip install mkdocs-include-markdown-plugin
pip install mkdocs-video
pip install mkdocs-literate-nav

Команды

Для разработки и проверки документации можно использовать команды:

• mkdocs serve – (с созданием pdf файлов) запуск локально сервера.

• mkdocs serve -f dev.yml (без создания pdf файлов)

• mkdocs build – сборка сайта в html формат. Собирается в каталог site.

• mkdocs build -f admin-manuals.yml (с созданием pdf файла с инструкциями для администратора)

Оформление текста

Чтобы включить увеличение изображения при помощи клика по нему, необходимо добавить {: .zoom} после объявления изображения, не отделяя пробелом.

<figure class="figure-image">
  <img src="../media/examplel.png" alt="Рисунок 1" class="zoom">
  <figcaption>Рисунок 1</figcaption>
</figure>

• 

несовместимо с img2fig, поэтому требует запуск zoom.ipynb для конвертации в вариант ниже:

<figure class="figure-image"> 
  <img src="example2.png" class="zoom" alt="Рисунок 2">
  <figcaption>Рисунок 2</figcaption>
</figure>

Фича была добавлена при помощи файлов extra.js и extra.css. При подключённом плагине img2fig можно использовать вариант 1, а затем прогнать скрипт в zoom.py, который сконвертирует все рисунки из всех *.md файлов из варианта 1 в вариант 2. Для этого необходимо запустить команду в консоли в папке с файлом zoom.py:

python zoom.py

В случае ошибки no library called "cairo" was found необходимо скачать библиотеки:

https://github.com/tschoonj/GTK-for-Windows-Runtime-Environment-Installer

https://github.com/tschoonj/GTK-for-Windows-Runtime-Environment-Installer/releases