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://eth1.ru 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
Начните загрузку
Дождитесь успешного окончания загрузки
Распакуйте архив
Подтвердите путь
Теперь сайт доступен по адресу
Вы можете перейти по ссылке и посмотреть не сломалось ли чего с момента последней проверки.
Ошибки
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
MkDocs | |
Python | |
Web |