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