MkDocs Python

Введение

MkDocs - это быстрый и простой генератор статических сайтов, предназначенный для создания проектной документации.

Исходные файлы документации записываются в Markdown и настраиваются с помощью одного файла конфигурации YAML.

Установка

python -m pip install mkdocs

Collecting mkdocs Downloading mkdocs-1.4.3-py3-none-any.whl (3.7 MB) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 3.7/3.7 MB 6.5 MB/s eta 0:00:00 Collecting click>=7.0 Using cached click-8.1.3-py3-none-any.whl (96 kB) Collecting colorama>=0.4 Using cached colorama-0.4.6-py2.py3-none-any.whl (25 kB) Collecting ghp-import>=1.0 Downloading ghp_import-2.1.0-py3-none-any.whl (11 kB) Collecting jinja2>=2.11.1 Downloading Jinja2-3.1.2-py3-none-any.whl (133 kB) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 133.1/133.1 kB ? eta 0:00:00 Collecting markdown<3.4,>=3.2.1 Downloading Markdown-3.3.7-py3-none-any.whl (97 kB) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 97.8/97.8 kB 5.8 MB/s eta 0:00:00 Collecting mergedeep>=1.3.4 Downloading mergedeep-1.3.4-py3-none-any.whl (6.4 kB) Collecting packaging>=20.5 Downloading packaging-23.1-py3-none-any.whl (48 kB) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 48.9/48.9 kB 2.6 MB/s eta 0:00:00 Collecting pyyaml-env-tag>=0.1 Downloading pyyaml_env_tag-0.1-py3-none-any.whl (3.9 kB) Collecting pyyaml>=5.1 Downloading PyYAML-6.0-cp311-cp311-win_amd64.whl (143 kB) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 143.2/143.2 kB 8.3 MB/s eta 0:00:00 Collecting watchdog>=2.0 Downloading watchdog-3.0.0-py3-none-win_amd64.whl (82 kB) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 82.0/82.0 kB ? eta 0:00:00 Collecting python-dateutil>=2.8.1 Downloading python_dateutil-2.8.2-py2.py3-none-any.whl (247 kB) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 247.7/247.7 kB 7.4 MB/s eta 0:00:00 Collecting MarkupSafe>=2.0 Downloading MarkupSafe-2.1.3-cp311-cp311-win_amd64.whl (17 kB) Collecting six>=1.5 Downloading six-1.16.0-py2.py3-none-any.whl (11 kB) Installing collected packages: watchdog, six, pyyaml, packaging, mergedeep, MarkupSafe, markdown, colorama, pyyaml-env-tag, python-dateutil, jinja2, click, ghp-import, mkdocs Successfully installed MarkupSafe-2.1.3 click-8.1.3 colorama-0.4.6 ghp-import-2.1.0 jinja2-3.1.2 markdown-3.3.7 mergedeep-1.3.4 mkdocs-1.4.3 packaging-23.1 python-dateutil-2.8.2 pyyaml-6.0 pyyaml-env-tag-0.1 six-1.16.0 watchdog-3.0.0

Новый сайт

mkdocs new documentation

INFO - Creating project directory: website INFO - Writing config file: website\mkdocs.yml INFO - Writing initial docs: website\docs\Overview.md

tree documentation/

documentation/ ├── docs │ └── index.md └── mkdocs.yml 1 directory, 2 files

serve - запуск сайта

mkdocs serve

INFO - Building documentation... INFO - Cleaning site directory INFO - Documentation built in 0.22 seconds INFO - [11:19:20] Watching paths for changes: 'docs', 'mkdocs.yml' INFO - [11:19:20] Serving on http://127.0.0.1:8000/

После успешного запуска вы можете увидеть свой сайт в браузере по адресу

http://127.0.0.1:8000

Этот режим нужен для ускорения разработки. При публикации сайта обычно используется команда build либо другие варианты, в зависимости от назначения.

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

По умолчанию доступны две темы: стандартная mkdocs и дополнительная readthedocs

На сайтах community wiki и Best-of-MkDocs можно найти список тем, созданных сторонними разработчиками.

Пример установки одной из таких тем - mkdocs-material. Она слегка напоминает мне мою тему для сайта eth1.ru

python -m pip install mkdocs-material

Collecting mkdocs-material Downloading mkdocs_material-9.1.18-py3-none-any.whl (7.8 MB) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 7.8/7.8 MB 18.6 MB/s eta 0:00:00 Requirement already satisfied: colorama>=0.4 in c:\users\andrei\mkdocs\venv\lib\site-packages (from mkdocs-material) (0.4.6) Requirement already satisfied: jinja2>=3.0 in c:\users\andrei\mkdocs\venv\lib\site-packages (from mkdocs-material) (3.1.2) Requirement already satisfied: markdown>=3.2 in c:\users\andrei\mkdocs\venv\lib\site-packages (from mkdocs-material) (3.3.7) Collecting mkdocs-material-extensions>=1.1 (from mkdocs-material) Downloading mkdocs_material_extensions-1.1.1-py3-none-any.whl (7.9 kB) Requirement already satisfied: mkdocs>=1.4.2 in c:\users\andrei\mkdocs\venv\lib\site-packages (from mkdocs-material) (1.4.3) Collecting pygments>=2.14 (from mkdocs-material) Downloading Pygments-2.15.1-py3-none-any.whl (1.1 MB) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 1.1/1.1 MB 24.2 MB/s eta 0:00:00 Collecting pymdown-extensions>=9.9.1 (from mkdocs-material) Downloading pymdown_extensions-10.0.1-py3-none-any.whl (240 kB) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 240.1/240.1 kB 15.3 MB/s eta 0:00:00 Collecting regex>=2022.4.24 (from mkdocs-material) Downloading regex-2023.6.3-cp311-cp311-win_amd64.whl (268 kB) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 268.0/268.0 kB ? eta 0:00:00 Collecting requests>=2.26 (from mkdocs-material) Downloading requests-2.31.0-py3-none-any.whl (62 kB) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 62.6/62.6 kB ? eta 0:00:00 Requirement already satisfied: MarkupSafe>=2.0 in c:\users\andrei\mkdocs\venv\lib\site-packages (from jinja2>=3.0->mkdocs-material) (2.1.3) Requirement already satisfied: click>=7.0 in c:\users\andrei\mkdocs\venv\lib\site-packages (from mkdocs>=1.4.2->mkdocs-material) (8.1.3) Requirement already satisfied: ghp-import>=1.0 in c:\users\andrei\mkdocs\venv\lib\site-packages (from mkdocs>=1.4.2->mkdocs-material) (2.1.0) Requirement already satisfied: mergedeep>=1.3.4 in c:\users\andrei\mkdocs\venv\lib\site-packages (from mkdocs>=1.4.2->mkdocs-material) (1.3.4) Requirement already satisfied: packaging>=20.5 in c:\users\andrei\mkdocs\venv\lib\site-packages (from mkdocs>=1.4.2->mkdocs-material) (23.1) Requirement already satisfied: pyyaml-env-tag>=0.1 in c:\users\andrei\mkdocs\venv\lib\site-packages (from mkdocs>=1.4.2->mkdocs-material) (0.1) Requirement already satisfied: pyyaml>=5.1 in c:\users\andrei\mkdocs\venv\lib\site-packages (from mkdocs>=1.4.2->mkdocs-material) (6.0) Requirement already satisfied: watchdog>=2.0 in c:\users\andrei\mkdocs\venv\lib\site-packages (from mkdocs>=1.4.2->mkdocs-material) (3.0.0) Collecting charset-normalizer<4,>=2 (from requests>=2.26->mkdocs-material) Downloading charset_normalizer-3.1.0-cp311-cp311-win_amd64.whl (96 kB) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 96.7/96.7 kB ? eta 0:00:00 Collecting idna<4,>=2.5 (from requests>=2.26->mkdocs-material) Downloading idna-3.4-py3-none-any.whl (61 kB) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 61.5/61.5 kB ? eta 0:00:00 Collecting urllib3<3,>=1.21.1 (from requests>=2.26->mkdocs-material) Downloading urllib3-2.0.3-py3-none-any.whl (123 kB) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 123.6/123.6 kB ? eta 0:00:00 Collecting certifi>=2017.4.17 (from requests>=2.26->mkdocs-material) Downloading certifi-2023.5.7-py3-none-any.whl (156 kB) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 157.0/157.0 kB ? eta 0:00:00 Requirement already satisfied: python-dateutil>=2.8.1 in c:\users\andrei\mkdocs\venv\lib\site-packages (from ghp-import>=1.0->mkdocs>=1.4.2->mkdocs-material) (2.8.2) Requirement already satisfied: six>=1.5 in c:\users\andrei\mkdocs\venv\lib\site-packages (from python-dateutil>=2.8.1->ghp-import>=1.0->mkdocs>=1.4.2->mkdocs-material) (1.16.0) Installing collected packages: urllib3, regex, pymdown-extensions, pygments, mkdocs-material-extensions, idna, charset-normalizer, certifi, requests, mkdocs-material Successfully installed certifi-2023.5.7 charset-normalizer-3.1.0 idna-3.4 mkdocs-material-9.1.18 mkdocs-material-extensions-1.1.1 pygments-2.15.1 pymdown-extensions-10.0.1 regex-2023.6.3 requests-2.31.0 urllib3-2.0.3

Затем нужно указать эту тему в mkdocs.yml

site_name: URN.SU theme: name: material

Если не установить нужную тему - получите ошибку Unrecognised theme name

nav: Панель навигации

По умолчанию в панели навигации присутствует вся структура сайта.

Если вы хотите изменять содержание панели навигации вручную - это можно сделать с помощью тега nav

В зависимости от темы содержимое nav располагается в верхнем меню (тема mkdoks) или в левом меню (тема material)

Пример:

nav: - Home: Overview.md - Ubuntu: linux/ubuntu/README.md

build: Сборка проекта

mkdocs build

INFO - Cleaning site directory INFO - Building documentation to directory: C:\Users\Andrei\mkdocs\website\site INFO - The following pages exist in the docs directory, but are not included in the "nav" configuration: - acronyms.md - qa_workflow\README.md - testcomplete\README.md INFO - Documentation built in 0.99 seconds

После сборки появится директория site с html файлами

echo "site/" >> .gitignore

gh-deploy: Деплой на github

Если у вас есть аккаунт на GitHub то сайт можно развернуть прямо там.

В директории в которой лежит проект documentation нужно инициализировать репозиторий и присоединить его к GitHub.

Подробнее о том как это делается читайте в статьях Git , remote и GitHub

git init
git clone git clone git@github.com:YouAccount/documentation.git
git add documentation
git commit -m "Original commit of documenation"
git push origin main

Если обычные Pull Request проходят успешно можно задеплоить сайт с помощью команды Git ,

mkdocs gh-deploy

INFO - Cleaning site directory INFO - Building documentation to directory: /mnt/c/Users/Andrei/documentation/site INFO - Documentation built in 1.26 seconds WARNING - Version check skipped: No version specified in previous deployment. INFO - Copying '/mnt/c/Users/Andrei/documentation/site' to 'gh-pages' branch and pushing to GitHub. Enumerating objects: 71, done. Counting objects: 100% (71/71), done. Delta compression using up to 24 threads Compressing objects: 100% (59/59), done. Writing objects: 100% (71/71), 566.77 KiB | 2.59 MiB/s, done. Total 71 (delta 9), reused 0 (delta 0), pack-reused 0 remote: Resolving deltas: 100% (9/9), done. remote: remote: Create a pull request for 'gh-pages' on GitHub by visiting: remote: https://github.com/AndreiOlegovich/documentation/pull/new/gh-pages remote: To github.com:AndreiOlegovich/documentation.git * [new branch] gh-pages -> gh-pages INFO - Your documentation should shortly be available at: https://AndreiOlegovich.github.io/documentation/

Мониторить статус можно на странице

https://github.com/YourRepo/documentation/actions

Если с первого раза не получилось можно повторить попытку. Это иногда помогает.

Также нужно проверить в настройках репозитория раздел Pages. Убедиться что для Deploy from a branch выбрана ветка gh-pages.

Пример

apt install python3.10-venv tree zip
python3 -m venv venv
source venv/bin/activate
python3 -m pip install mkdocs
python3 -m pip install mkdocs-material
mkdocs new documentation
tree documentation

documentation/ ├── docs │ └── index.md └── mkdocs.yml

cd docs
mkdir assets linux python qa
touch linux/Overview.md python/Overview.md qa/Overview.md
mkdir linux/ubuntu assets/img
touch linux/ubuntu/Overview.md
cd ../..
tree documentation

documentation/ ├── docs │ ├── assets │ │ └── img │ │ └── favicon.ico │ ├── index.md │ ├── linux │ │ ├── Overview.md │ │ └── ubuntu │ │ └── Overview.md │ ├── python │ │ └── Overview.md │ └── qa │ └── Overview.md └── mkdocs.yml 4 directories, 5 files

cd documentation
vi mkdocs.yml

site_name: URN.su site_url: https://urn.su theme: name: material favicon: assets/img/favicon.ico palette: primary: teal accent: orange

mkdocs serve

Демонстрация сайта доступна на порту 8000

Сайт адаптивный. Сперва при сужении экрана отпадает левое меню.

Затем и правое

tree -L 2 documentation/

documentation/ ├── docs │ ├── assets │ ├── index.md │ ├── linux │ ├── python │ └── qa ├── mkdocs.yml └── site ├── 404.html ├── assets ├── index.html ├── linux ├── python ├── qa ├── search ├── sitemap.xml └── sitemap.xml.gz

git init
ls -la

. .. .git documentation

git add documentation
git commit -m "Original commit of documenation"
git push origin main

mkdocs gh-deploy

Деплой на виртуальном хостинге

Если нужно иметь сайт не в GitHub а на своём хостинге, то я рекомендую всем хостинг Beget.com, которым пользуюсь с начала 2010-х годов.

Сперва в той же директории, где находится файл mkdocs.yml выполните

zip -r demo.zip site

В результате должен быть создан архив demo.zip

Залогиньтесь на хостинге и перейдите в тот сайт, где хотите развернуть документацию на основе mkdocs.

В примере я делаю это на сайте devhops.ru в директории demo

Нажмите на Загрузить Файлы

Нажмите на Browse

Найдите архив demo.zip

Начните загрузку

Дождитесь успешного окончания загрузки

Распакуйте архив

Подтвердите путь

Теперь сайт доступен по адресу

https://devhops.ru/demo/site/

Вы можете перейти по ссылке и посмотреть не сломалось ли чего с момента последней проверки.

Ошибки

ERROR - Config value 'theme': Unrecognised theme name: 'material'. The available installed themes are: mkdocs, readthedocs

Run actions/deploy-pages@v2 Artifact exchange URL: https://pipelines.actions.githubusercontent.com/haFuYVXQX3f3rCnlAt4RI6gqcVqQcgGMaCg1tAb5xbT1gc3oVA/_apis/pipelines/workflows/5473916641/artifacts?api-version=6.0-preview Creating Pages deployment with payload: { "artifact_url": "https://pipelines.actions.githubusercontent.com/haFuYVXQX3f3rCnlAt4RI6gqcVqQcgGMaCg1tAb5xbT1gc3oVA/_apis/pipelines/1/runs/1/artifacts?artifactName=github-pages&%24expand=SignedContent", "pages_build_version": "067302cd6679560e1d0133ba13be8e643dcebd57", "oidc_token": "***" } Error: Creating Pages deployment failed Error: HttpError: Server Error at /home/runner/work/_actions/actions/deploy-pages/v2/webpack:/deploy-pages/node_modules/@octokit/request/dist-node/index.js:86:1 at processTicksAndRejections (node:internal/process/task_queues:96:5) at createPagesDeployment (/home/runner/work/_actions/actions/deploy-pages/v2/webpack:/deploy-pages/src/internal/api-client.js:126:1) at Deployment.create (/home/runner/work/_actions/actions/deploy-pages/v2/webpack:/deploy-pages/src/internal/deployment.js:79:1) at main (/home/runner/work/_actions/actions/deploy-pages/v2/webpack:/deploy-pages/src/index.js:30:1) Error: TypeError: Converting circular structure to JSON --> starting at object with constructor 'TLSSocket' | property '_httpMessage' -> object with constructor 'ClientRequest' --- property 'socket' closes the circle