MkDocs (віртуальне середовище Python)¶
Вступ¶
Одним із аспектів процесу створення документації для Rocky Linux є перевірка правильності відображення нового документа перед публікацією.
Метою цього посібника є надання деяких порад щодо виконання цього завдання в локальному середовищі python, призначеному виключно для цієї мети.
Документація для Rocky Linux написана з використанням мови Markdown, яка зазвичай конвертується в інші формати. Markdown має чистий синтаксис і особливо добре підходить для написання технічної документації.
У нашому випадку документація перетворюється на HTML
за допомогою програми python, яка піклується про створення статичного сайту. Розробники використовують програму MkDocs.
Одна з проблем, яка виникає під час розробки програми python, полягає в тому, щоб ізолювати примірник python, який використовується для розробки, від системного інтерпретатора. Ізоляція запобігає несумісності між модулями, необхідними для встановлення програми Python, і тими, які встановлені на хост-системі.
Уже існують чудові посібники, які використовують контейнери для ізоляції інтерпретатора Python. Ці посібники, однак, передбачають знання різних методів контейнеризації.
У цьому посібнику для розділення використовується модуль venv
, що надається пакетом python Rocky Linux. Цей модуль доступний у всіх нових версіях Python, починаючи з версії 3.6. Це дозволить напряму досягти ізоляції інтерпретатора Python у системі без необхідності інсталювати та налаштовувати нові "системи".
Вимоги¶
- запущена копія Rocky Linux
- пакет python встановлено правильно
- знайомство з командним рядком
- активне підключення до Інтернету
Підготовка середовища¶
Середовище надає кореневу папку, що містить два необхідні репозиторії Rocky Linux GitHub і папку, де відбувається ініціалізація та запуск вашої копії python у віртуальному середовищі.
Спершу створіть папку, яка міститиме все інше, а також контекстно створіть папку env, де запускатиметься MkDocs:
mkdir -p ~/lab/rockydocs/env
Віртуальне середовище Python¶
Щоб створити свою копію Python, де працюватиме MkDocs, скористайтеся модулем python venv
, спеціально розробленим для цієї мети. Це дозволяє створити віртуальне середовище, похідне від встановленого в системі, повністю ізольоване та незалежне.
Це дозволить нам мати копію інтерпретатора в окремій папці лише з пакетами, які потрібні MkDocs
для запуску документації Rocky Linux.
Перейдіть до щойно створеної папки (rockydocs) і створіть віртуальне середовище за допомогою:
cd ~/lab/rockydocs/
python -m venv env
Ця команда заповнить папку env серією папок і файлів, які імітують дерево python вашої системи, показано тут:
env/
├── bin
│ ├── activate
│ ├── activate.csh
│ ├── activate.fish
│ ├── Activate.ps1
│ ├── pip
│ ├── pip3
│ ├── pip3.11
│ ├── python -> /usr/bin/python
│ ├── python3 -> python
│ └── python3.11 -> python
├── include
│ └── python3.11
├── lib
│ └── python3.11
├── lib64 -> lib
└── pyvenv.cfg
Як бачите, інтерпретатор python, який використовується віртуальним середовищем, усе ще доступний у системі python -> /usr/bin/python
. Процес віртуалізації дбає лише про ізоляцію вашого екземпляра.
Активація віртуального середовища¶
Серед файлів, перелічених у структурі, є декілька файлів під назвою activate, які служать для цієї мети. Суфікс кожного файлу вказує на відповідну оболонку.
Активація відокремлює цей екземпляр python від екземпляра системи та дозволяє нам виконувати розробку документації без втручання. Щоб активувати його, перейдіть до папки env і виконайте команду:
[rocky_user@rl9 rockydocs]$ cd ~/lab/rockydocs/env/
[rocky_user@rl9 env]$ source ./bin/activate
Команду activate було видано без суфікса, оскільки це стосується оболонки bash, оболонки Rocky Linux за замовчуванням. На цьому етапі ваша підказка оболонки має бути такою:
(env) [rocky_user@rl9 env]$
Як бачите, початкова частина (env) вказує на те, що ви перебуваєте у віртуальному середовищі. Перше, що потрібно зробити на цьому етапі, це оновити pip, менеджер модулів python, який використовуватиметься для встановлення MkDocs. Для цього використовуйте команду:
python -m pip install --upgrade pip
python -m pip install --upgrade pip
Requirement already satisfied: pip in ./lib/python3.9/site-packages (21.2.3)
Collecting pip
Downloading pip-23.1-py3-none-any.whl (2.1 MB)
|████████████████████████████████| 2.1 MB 1.6 MB/s
Installing collected packages: pip
Attempting uninstall: pip
Found existing installation: pip 21.2.3
Uninstalling pip-21.2.3:
Successfully uninstalled pip-21.2.3
Successfully installed pip-23.1
Деактивація середовища¶
Щоб вийти з віртуального середовища, скористайтеся командою deactivate:
(env) [rocky_user@rl9 env]$ deactivate
[rocky_user@rl9 env]$
Як бачите, підказка після деактивації повернулася до системної. Завжди уважно перевіряйте підказку перед запуском інсталяції MkDocs і подальших команд. Позначте цей прапорець, щоб запобігти непотрібним і небажаним глобальним встановленням програм і пропущеним запускам mkdocs serve
.
Завантаження репозиторіїв¶
Тепер, коли ви побачили, як створити своє віртуальне середовище та як ним керувати, ви можете переходити до підготовки всього необхідного.
Для реалізації локальної версії документації Rocky Linux потрібні два репозиторії: сховище документації documentation та сховище структури сайту docs.rockylinux.org. Їх завантаження здійснюється з Rocky Linux GitHub.
Почніть зі сховища структури сайту, яке ви клонуєте в папку rockydocs:
cd ~/lab/rockydocs/
git clone https://github.com/rocky-linux/docs.rockylinux.org.git
У цій папці є два файли, які ви збираєтеся використовувати для створення локальної документації. Це mkdocs.yml, файл конфігурації, який використовується для ініціалізації MkDocs, і requirement.txt, який містить усі пакети python, необхідні для встановлення mkdocs.
Після завершення вам також потрібно завантажити репозиторій документації:
git clone https://github.com/rocky-linux/documentation.git
На цьому етапі ви матимете таку структуру в папці rockydocs:
rockydocs/
├── env
├── docs.rockylinux.org
├── documentation
Схематично ви можете сказати, що папка env буде вашим механізмом MkDocs, який використовуватиме docs.rockylinux.org як контейнер для відображення даних, що містяться в документації.
Установка MkDocs¶
Як зазначалося раніше, розробники Rocky Linux надають файл requirement.txt, який містить список модулів, необхідних для належного запуску спеціального екземпляра MkDocs. Ви будете використовувати файл, щоб установити все необхідне за одну операцію.
Спочатку ви входите у своє віртуальне середовище python:
[rocky_user@rl9 rockydocs]$ cd ~/lab/rockydocs/env/
[rocky_user@rl9 env]$ source ./bin/activate
(env) [rocky_user@rl9 env]$
Далі перейдіть до встановлення MkDocs і всіх його компонентів за допомогою команди:
(env) [rocky_user@rl9 env]$ python -m pip install -r ../docs.rockylinux.org/requirements.txt
Щоб перевірити, чи все пройшло добре, ви можете викликати довідку MkDocs, яка також знайомить нас із доступними командами:
(env) [rocky_user@rl9 env]$ mkdocs -h
Usage: mkdocs [OPTIONS] COMMAND [ARGS]...
MkDocs - Проектна документація з Markdown.
Опції:
-V, --version Показує версію та вихід.
-q, --quiet Попередження про тишу
-v, --verbose Вмикає докладний вивід
-h, --help Показує це повідомлення та виходить.
Команди:
build Збирає документацію MkDocs
gh-deploy Розгортає вашу документацію на сторінках GitHub
new Створює новий проект MkDocs
serve Запускає вбудований сервер розробки
Якщо все спрацювало, як планувалося, ви можете вийти з віртуального середовища і почати підготовку необхідних підключень.
(env) [rocky_user@rl9 env]$ deactivate
[rocky_user@rl9 env]$
Приєднання документації¶
Тепер, коли все необхідне доступне, вам просто потрібно зв’язати сховище документації на веб-сайті контейнера docs.rockylinux.org. Дотримуючись налаштувань, визначених у mkdocs.yml:
docs_dir: 'docs/docs'
Спершу потрібно створити папку docs на docs.rockylinux.org, а потім у ній пов’язати свою папку docs зі сховища документації.
cd ~/lab/rockydocs/docs.rockylinux.org
mkdir docs
cd docs/
ln -s ../../documentation/docs/ docs
Запуск локальної документації¶
На цьому етапі ви готові почати локальну копію документації Rocky Linux. Спочатку вам потрібно запустити віртуальне середовище python, а потім ініціалізувати свій екземпляр MkDocs із налаштуваннями, визначеними в docs.rockylinux.org/mkdocs.yml.
Цей файл містить усі параметри для локалізації, керування функціями та темами.
Розробники інтерфейсу користувача сайту обрали тему Material for MkDocs, яка надає багато додаткових функцій і налаштувань порівняно зі стандартною темою MkDocs.
Виконайте наступні команди:
[rocky_user@rl9 rockydocs]$ cd ~/lab/rockydocs/env/
[rocky_user@rl9 rockydocs]$ source ./bin/activate
(env) [rocky_user@rl9 env]$ mkdocs serve -f ../docs.rockylinux.org/mkdocs.yml
Ви повинні побачити у своєму терміналі початок білду сайту. На дисплеї відображатимуться будь-які помилки, знайдені MkDocs, наприклад, відсутні посилання чи інші:
INFO - Building documentation...
INFO - Adding 'de' to the 'plugins.search.lang' option
INFO - Adding 'fr' to the 'plugins.search.lang' option
INFO - Adding 'es' to the 'plugins.search.lang' option
INFO - Adding 'it' to the 'plugins.search.lang' option
INFO - Adding 'ja' to the 'plugins.search.lang' option
...
...
INFO - Documentation built in 102.59 seconds
INFO - [11:46:50] Watching paths for changes:
'/home/rocky_user/lab/rockydocs/docs.rockylinux.org/docs/docs',
'/home/rocky_user/lab/rockydocs/docs.rockylinux.org/mkdocs.yml'
INFO - [11:46:50] Serving on http://127.0.0.1:8000/
Ваша копія сайту документації буде запущена під час відкриття вашого браузера за вказаною адресою http://127.0.0.1:8000. Копія ідеально відображає онлайн-сайт за функціональністю та структурою, дозволяючи оцінити зовнішній вигляд і вплив вашої сторінки на сайт.
MkDocs містить механізм для перевірки змін у файлах у папці, визначеній шляхом docs_dir
, і вставлення нової сторінки або зміна існуючої в documentation/docs
буде автоматично розпізнано та створить нову статичну збірку сайту.
Оскільки MkDocs створює статичний сайт за кілька хвилин, радимо уважно переглянути сторінку, яку ви пишете, перш ніж зберігати або вставляти її. Це економить чекання створення сайту лише тому, що ви забули, наприклад, знаки пунктуації.
Вихід із середовища розробки¶
Коли відображення нової сторінки задовольнить вас, ви можете вийти з середовища розробки. Для цього потрібно спочатку вийти з MkDocs, а потім дезактивувати віртуальне середовище python. Щоб вийти з MkDocs, вам потрібно використати комбінацію клавіш Ctrl + C, і, як ви бачили вище, щоб вийти з віртуального середовища, вам потрібно буде викликати deactivate
.
...
INFO - [22:32:41] Serving on http://127.0.0.1:8000/
^CINFO - Shutting down...
(env) [rocky_user@rl9 env]$
(env) [rocky_user@rl9 env]$ deactivate
[rocky_user@rl9 env]$
Висновки та заключні думки¶
Перевірка ваших нових сторінок на сайті локальної розробки гарантує нам, що ваша робота завжди відповідатиме веб-сайту онлайн-документації, дозволяючи нам робити оптимальний внесок.
Відповідність документів також є великою підмогою для кураторів сайту документації, яким потім залишається лише займатися коректністю контенту.
На завершення можна сказати, що цей метод дозволяє виконати вимоги щодо «чистої» інсталяції MkDocs без необхідності вдаватися до контейнеризації.
Author: Franco Colussi
Contributors: Steven Spencer, Ganna Zhyrnova