Skip to content

MkDocs

MkDocs – это бесплатный статический генератор сайтов , предназначенный для создания проектной документации. Документация размещается с помощью бесплатных сервисов, например Read The Docs, или же на собственном сервере.

MkDocs написан на Python. Исходные файлы документации написаны на Markdown и настроены с помощью одного файла конфигурации YAML. Генератор сайтов MkDocs в качестве исходных материалов поддерживает файлы как формата markdown (.md) так и формата html.

Этапы установки:

  • Установка Python

  • Установка pip (если версия Python 3.4 или новее, то возможно pip уже установлен)- get-pip.py - Команда для установки python get-pip.py

  • Установка mkdocs - команда pip install mkdocs

Создание нового проекта:

  • Выполнить команды в командной строке - mkdocs new my-project, cd my-project. Существует один файл конфигурации с именем mkdocs.yml и папка с именем docs, которая будет содержать исходные файлы документации.

  • Запустите сервер, выполнив команду - mkdocs serve

  • Откройте http://127.0.0.1:8000/ в своем браузере, и вы увидите, что отображается домашняя страница по умолчанию. Сервер разработки также поддерживает автоматическую перезагрузку и будет перестраивать вашу документацию всякий раз, когда что-либо изменяется в файле конфигурации, каталоге документации или каталоге темы.

  • Откройте docs/index.md документ в выбранном вами текстовом редакторе, измените начальный заголовок и сохраните изменения. Ваш браузер автоматически перезагрузится, и вы сразу увидите обновленную документацию.

  • Теперь отредактируйте файл конфигурации: mkdocs.yml. Измените site_name настройку и сохраните файл.

  • Добавьте вторую страницу в документацию - docs/about.md

  • Поскольку сайт документации будет включать в себя некоторые навигационные заголовки, можно отредактировать файл конфигурации mkdocs.yml и добавить некоторую информацию о порядке, заголовке и вложенности каждой страницы в навигационный заголовок, добавив nav параметр: nav:

    • Home: index.md
    • About: about.md

  • Теперь изменим файл конфигурации, чтобы изменить способ отображения документации, изменив тему. Отредактируем mkdocs.yml файл и добавим theme параметр (например: read the docs).

  • Изменение значка фавиконки. По умолчанию MkDocs использует значок избранного MkDocs . Чтобы использовать другой значок, создайте img подкаталог в docs каталоге и скопируйте свой пользовательский favicon.ico файл в этот каталог. MkDocs автоматически обнаружит этот файл и будет использовать его в качестве значка фавикона.

  • Создание сайта. Сбор документации - команда mkdocs build. Это создаст новый каталог с именем site.

Развертывание:

Сайт документации использует только статические файлы, поэтому вы сможете разместить его практически из любого места. Просто загрузите содержимое всего site каталога туда, где вы размещаете свой веб-сайт, и все готово.

Страницы проекта.

Сайты Project Pages проще, поскольку файлы сайта развертываются в ветке в репозитории проекта ( gh-pages по умолчанию). После того, как вы откроете основную рабочую ветку (обычно master) репозитория git, в которой хранится исходная документация для вашего проекта, выполните следующую команду: mkdocs gh-deploy

Вот и все! За кулисами MkDocs создаст ваши документы и с помощью инструмента ghp-import зафиксирует их в gh-pages ветке и отправит gh-pages ветку на GitHub.

Модернизация документации.

Следующий этап — это добавление сайта в систему контроля версии (СКВ) и написание скрипта, который сам собирал бы нам сайт как только мы сохраним новую его версию. Воспользуемся git-ом как СКВ и Gitlab CI для обработки действий. Теперь, когда репозиторий создан и связан с Gitlab, создадим в папке с исходными материалами файл .gitlab-ci.yml stages: 

- build 
build_docs_job: 
stage: build 
 only: 
- /^master$/
 - merge_requests 
image: 
name: squidfunk/mkdocs-material 
entrypoint: [""] 
script: 
- 'mkdocs build --site-dir site' 
artifacts: 
name: "site_$($CI_PIPELINE_IID)" 
paths: 
- site

Этим файлом мы указали Gitlab CI собирать сайт каждый раз, когда появляются новые коммиты в ветке master. Также потребуется установить Gitlab Runner на машину, которая и будет собирать сайт по написанной в файле .gitlab-ci.yml «инструкции».