94 lines
4.1 KiB
Markdown
94 lines
4.1 KiB
Markdown
# Инструкция по установке
|
||
|
||
## MkDocs
|
||
|
||
Инструкция по установке есть на [сайте MkDocs](https://www.mkdocs.org/#installation).
|
||
|
||
Надо установить:
|
||
* python [python.org](https://www.python.org/downloads/) !!!
|
||
* pip – менеджер пакет (ставится, обычно, вместе с питоном)
|
||
* mkdocs – пакет с движком mkdocs
|
||
```bash
|
||
|
||
```
|
||
Полезные ссылки:
|
||
|
||
* [mkdocs.org](https://www.mkdocs.org/)
|
||
* [плагины MkDocs](https://github.com/mkdocs/mkdocs/wiki/MkDocs-Plugins)
|
||
* [Темы MkDocs](https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes)
|
||
* [markdown дополнения](https://python-markdown.github.io/extensions/)
|
||
|
||
## Тема
|
||
|
||
В проекте используется тема [material](https://squidfunk.github.io/mkdocs-material/getting-started/).
|
||
|
||
Для установки запускаем:
|
||
```bash
|
||
pip install mkdocs-material
|
||
```
|
||
|
||
Полезные ссылки:
|
||
|
||
* [Настройки темы material](https://squidfunk.github.io/mkdocs-material/getting-started/)
|
||
* [Плагины из темы material](https://squidfunk.github.io/mkdocs-material/reference/abbreviations/)
|
||
* [Проект темы material на GitHub](https://github.com/squidfunk/mkdocs-material)
|
||
|
||
## Плагины
|
||
|
||
В проекте используются плагины:
|
||
* [search](https://github.com/mkdocs/mkdocs/wiki/MkDocs-Plugins#search) – встроенный плагин поиска.
|
||
* [img2fig](https://github.com/mkdocs/mkdocs/wiki/MkDocs-Plugins#img2fig) – отображение картинок в отдельном теге с подписью внизу.
|
||
|
||
```bash
|
||
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} после объявления изображения, не отделяя пробелом.
|
||
|
||
1.
|
||
```html
|
||
<figure class="figure-image">
|
||
<img src="../media/examplel.png" alt="Рисунок 1" class="zoom">
|
||
<figcaption>Рисунок 1</figcaption>
|
||
</figure>
|
||
```
|
||
* <img alt="Рисунок 1" src="examplel.png" class="zoom"/>
|
||
несовместимо с **img2fig**, поэтому **требует запуск zoom.ipynb** для конвертации в вариант ниже:
|
||
|
||
2.
|
||
```html
|
||
<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:
|
||
|
||
```console
|
||
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
|