MkDocs – генерация документации для проектов

Введение

Почему документация — это не опция, а необходимость

В современном мире open-source и разработок на Python, качественная документация — ключ к успеху любого проекта. Недостаток документации отпугивает потенциальных контрибьюторов и пользователей. Однако написание и поддержание её часто откладывается в долгий ящик.

Здесь на сцену выходит MkDocs — мощный генератор документации, простой в установке, поддерживающий Markdown и позволяющий создать красивый сайт без знания HTML или CSS.

Что такое MkDocs

Краткий обзор

MkDocs — это статический генератор сайтов, написанный на Python, оптимизированный для создания проектной документации. Он преобразует Markdown-файлы в полнофункциональный HTML-сайт.

• Лицензия: MIT

• Язык: Python

• Исходники: GitHub MkDocs

• Альтернатива: Sphinx, Docsify, GitBook

Ключевые возможности

• Поддержка Markdown

• Легкая конфигурация через mkdocs.yml

• Поддержка тем (в т.ч. Material)

• Плагины и расширения

• Автоматический локальный сервер (mkdocs serve)

Установка и запуск

Требования

• Python 3.7+

• pip (Python package installer)

Установка MkDocs

pip install mkdocs

Базовая структура проекта

my-project/
├── docs/
│   └── index.md
└── mkdocs.yml

Запуск локального сервера

mkdocs serve

Сборка сайта

mkdocs build

Генерирует директорию site/ с HTML-версией документации.

Конфигурационный файл mkdocs.yml

Основные параметры

Параметр	Назначение
site_name	Название сайта
nav	Навигация и структура
theme	Тема оформления
plugins	Список активных плагинов
markdown_extensions	Расширения Markdown

Пример:

site_name: My Project Docs
nav:
  - Home: index.md
  - API: api.md
theme:
  name: material
plugins:
  - search
  - macros
markdown_extensions:
  - toc
  - admonition

Темы оформления

Официальные темы

• mkdocs (по умолчанию)

• readthedocs

Material for MkDocs

Самая популярная тема — Material for MkDocs.

Установка:

pip install mkdocs-material

Преимущества:

• Поддержка dark mode

• Навигация по боковой панели

• Мобильная адаптация

• Интеграция с GitHub Pages

Продвинутые фишки:

• Плавающее оглавление

• Кастомные шорткоды

• Таблицы версий, вкладки, алерты

Плагины MkDocs

Что такое плагин?

Плагины расширяют функциональность генерации: от автогенерации API до вставки динамических блоков.

Популярные плагины

Плагин	Назначение
search	Поиск по сайту (встроен)
macros	Макросы на Jinja2
mkdocstrings	Документация по коду автоматически
awesome-pages	Улучшение структуры навигации
include-markdown	Вставка других Markdown-файлов

Установка плагинов

pip install mkdocs-macros-plugin mkdocstrings

Пример использования macros

# main.py
def define_env(env):
    env.variables['version'] = '1.0.3'

В Markdown: {{ version }} → отобразит 1.0.3

Markdown и расширения

Расширенные возможности Markdown

Расширение	Назначение
admonition	Инфо-блоки (Note, Warning и т.п.)
codehilite	Подсветка кода
toc	Автоматическое оглавление
pymdownx.*	Множество визуальных улучшений

Пример admonition

!!! warning "Осторожно"
    Этот раздел требует повышенного внимания.

Интеграция с GitHub Pages

Автоматическая публикация

mkdocs gh-deploy

Создает и заливает сайт в ветку gh-pages

Подключение к GitHub Actions

# .github/workflows/mkdocs.yml
name: Deploy Docs
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Set up Python
        uses: actions/setup-python@v2
      - run: pip install mkdocs mkdocs-material
      - run: mkdocs gh-deploy --force

Кейсы использования

Кейс 1: Документация Python-библиотеки

Автор небольшой библиотеки использует mkdocstrings для автоматической генерации описаний функций и классов. Интерфейс — в стиле Material. Весь процесс занимает <1 дня.

Кейс 2: Внутренняя документация компании

Технический отдел создает внутреннюю документацию: схемы БД, API, гайды по развертке. Используются Markdown-файлы и плагин include-markdown для сборки из разных частей.

Все функции библиотеки MkDocs для питона

mkdocs.commands.build.build(config)

Назначение

Генерирует HTML-сайт из Markdown-файлов.

Аргументы

• config: объект конфигурации mkdocs.config.Config.

Возвращает

None

Пример использования

---

mkdocs.commands.serve.serve(config, livereload=True, watch=None, dirty=False)

Назначение

Запускает локальный сервер с автообновлением.

Аргументы

• config: объект конфигурации

• livereload: включает LiveReload (по умолчанию True)

• watch: дополнительные пути для отслеживания

• dirty: пересборка только изменённых файлов

Возвращает

None

---

mkdocs.commands.gh_deploy.gh_deploy(...)

Назначение

Публикует сайт на GitHub Pages.

Аргументы

• config: конфигурация проекта

• message: коммит-сообщение

• force: форсированный пуш

• ignore_version: игнорировать несовпадение версий

• remote_branch: ветка (gh-pages)

• remote_name: имя удалённого (origin)

Возвращает

None

---

mkdocs.commands.new.new(project_dir)

Назначение

Создаёт новую структуру проекта MkDocs.

Аргументы

• project_dir: путь к новому проекту

Возвращает

None

---

mkdocs.config.load_config(*args, **kwargs)

Назначение

Загружает и валидирует конфигурацию из mkdocs.yml.

Возвращает

Экземпляр mkdocs.config.Config.

---

mkdocs.config.defaults.get_schema()

Назначение

Возвращает схему валидной конфигурации.

Возвращает

Объект схемы конфигурации (Schema).

---

Класс mkdocs.structure.nav.Navigation

Назначение

Отражает структуру навигации документации.

Методы

• Navigation(items, config) — конструктор

• to_context() — возвращает словарь для шаблонов

---

Класс mkdocs.structure.pages.Page

Назначение

Представляет одну страницу документации.

Атрибуты

• title, content, url, edit_url

Методы

• render(template) — рендер страницы

---

Класс mkdocs.structure.files.Files

Назначение

Управление всеми файлами проекта.

Методы

• get_file_from_path(path) — файл по пути

• documentation_pages() — список страниц

---

mkdocs.utils.clean_directory(path)

Назначение

Удаляет всё содержимое указанной директории.

---

mkdocs.utils.copy_file(source, destination)

Назначение

Копирует файл из одного пути в другой.

---

mkdocs.plugins.BasePlugin

Назначение

Базовый класс для создания плагинов MkDocs.

Переопределяемые методы

• on_config(config)

• on_pre_build(config)

• on_files(files, config)

• on_page_markdown(markdown, page, config, files)

• on_page_content(html, page, config, files)

• on_post_build(config)

Заключение

Почему стоит использовать MkDocs

• Просто: низкий порог входа

• Гибко: десятки плагинов и тем

• Красиво: Material делает сайт современным

• Быстро: результат виден сразу

Рекомендации

• Используйте Material для внешних проектов

• Настройте GitHub Actions для автодеплоя

• Добавьте macros и mkdocstrings для продвинутой генерации