Одним із аспектів процесу створення документації для Rocky Linux є перевірка правильності відображення нового документа перед публікацією.
Метою цього посібника є надання деяких порад щодо виконання цього завдання в локальному середовищі python, призначеному виключно для цієї мети.
Документація для Rocky Linux написана з використанням мови Markdown, яка зазвичай конвертується в інші формати. Markdown має чистий синтаксис і особливо добре підходить для написання технічної документації.
У нашому випадку документація перетворюється на HTML за допомогою програми python, яка піклується про створення статичного сайту. Розробники використовують програму MkDocs.
Одна з проблем, яка виникає під час розробки програми python, полягає в тому, щоб ізолювати примірник python, який використовується для розробки, від системного інтерпретатора. Ізоляція запобігає несумісності між модулями, необхідними для встановлення програми Python, і тими, які встановлені на хост-системі.
Уже існують чудові посібники, які використовують контейнери для ізоляції інтерпретатора Python. Ці посібники, однак, передбачають знання різних методів контейнеризації.
У цьому посібнику для розділення використовується модуль venv, що надається пакетом python Rocky Linux. Цей модуль доступний у всіх нових версіях Python, починаючи з версії 3.6. Це дозволить напряму досягти ізоляції інтерпретатора Python у системі без необхідності інсталювати та налаштовувати нові "системи".
Середовище надає кореневу папку, що містить два необхідні репозиторії Rocky Linux GitHub і папку, де відбувається ініціалізація та запуск вашої копії python у віртуальному середовищі.
Спершу створіть папку, яка міститиме все інше, а також контекстно створіть папку env, де запускатиметься MkDocs:
Щоб створити свою копію Python, де працюватиме MkDocs, скористайтеся модулем python venv, спеціально розробленим для цієї мети. Це дозволяє створити віртуальне середовище, похідне від встановленого в системі, повністю ізольоване та незалежне.
Це дозволить нам мати копію інтерпретатора в окремій папці лише з пакетами, які потрібні MkDocs для запуску документації Rocky Linux.
Перейдіть до щойно створеної папки (rockydocs) і створіть віртуальне середовище за допомогою:
cd~/lab/rockydocs/
python-mvenvenv
Ця команда заповнить папку env серією папок і файлів, які імітують дерево python вашої системи, показано тут:
Як бачите, інтерпретатор python, який використовується віртуальним середовищем, усе ще доступний у системі python -> /usr/bin/python. Процес віртуалізації дбає лише про ізоляцію вашого екземпляра.
Серед файлів, перелічених у структурі, є декілька файлів під назвою activate, які служать для цієї мети. Суфікс кожного файлу вказує на відповідну оболонку.
Активація відокремлює цей екземпляр python від екземпляра системи та дозволяє нам виконувати розробку документації без втручання. Щоб активувати його, перейдіть до папки env і виконайте команду:
Команду activate було видано без суфікса, оскільки це стосується оболонки bash, оболонки Rocky Linux за замовчуванням. На цьому етапі ваша підказка оболонки має бути такою:
(env)[rocky_user@rl9env]$
Як бачите, початкова частина (env) вказує на те, що ви перебуваєте у віртуальному середовищі. Перше, що потрібно зробити на цьому етапі, це оновити pip, менеджер модулів python, який використовуватиметься для встановлення MkDocs. Для цього використовуйте команду:
Як бачите, підказка після деактивації повернулася до системної. Завжди уважно перевіряйте підказку перед запуском інсталяції MkDocs і подальших команд. Позначте цей прапорець, щоб запобігти непотрібним і небажаним глобальним встановленням програм і пропущеним запускам mkdocs serve.
Тепер, коли ви побачили, як створити своє віртуальне середовище та як ним керувати, ви можете переходити до підготовки всього необхідного.
Для реалізації локальної версії документації Rocky Linux потрібні два репозиторії: сховище документації documentation та сховище структури сайту docs.rockylinux.org. Їх завантаження здійснюється з Rocky Linux GitHub.
Почніть зі сховища структури сайту, яке ви клонуєте в папку rockydocs:
У цій папці є два файли, які ви збираєтеся використовувати для створення локальної документації. Це mkdocs.yml, файл конфігурації, який використовується для ініціалізації MkDocs, і requirement.txt, який містить усі пакети python, необхідні для встановлення mkdocs.
Після завершення вам також потрібно завантажити репозиторій документації:
Схематично ви можете сказати, що папка env буде вашим механізмом MkDocs, який використовуватиме docs.rockylinux.org як контейнер для відображення даних, що містяться в документації.
Як зазначалося раніше, розробники Rocky Linux надають файл requirement.txt, який містить список модулів, необхідних для належного запуску спеціального екземпляра MkDocs. Ви будете використовувати файл, щоб установити все необхідне за одну операцію.
Спочатку ви входите у своє віртуальне середовище python:
Тепер, коли все необхідне доступне, вам просто потрібно зв’язати сховище документації на веб-сайті контейнера docs.rockylinux.org. Дотримуючись налаштувань, визначених у mkdocs.yml:
docs_dir:'docs/docs'
Спершу потрібно створити папку docs на docs.rockylinux.org, а потім у ній пов’язати свою папку docs зі сховища документації.
На цьому етапі ви готові почати локальну копію документації Rocky Linux. Спочатку вам потрібно запустити віртуальне середовище python, а потім ініціалізувати свій екземпляр MkDocs із налаштуваннями, визначеними в docs.rockylinux.org/mkdocs.yml.
Цей файл містить усі параметри для локалізації, керування функціями та темами.
Розробники інтерфейсу користувача сайту обрали тему Material for MkDocs, яка надає багато додаткових функцій і налаштувань порівняно зі стандартною темою MkDocs.
Ви повинні побачити у своєму терміналі початок білду сайту. На дисплеї відображатимуться будь-які помилки, знайдені 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.
Перевірка ваших нових сторінок на сайті локальної розробки гарантує нам, що ваша робота завжди відповідатиме веб-сайту онлайн-документації, дозволяючи нам робити оптимальний внесок.
Відповідність документів також є великою підмогою для кураторів сайту документації, яким потім залишається лише займатися коректністю контенту.
На завершення можна сказати, що цей метод дозволяє виконати вимоги щодо «чистої» інсталяції MkDocs без необхідності вдаватися до контейнеризації.