Будівельна документація¶
Перш ніж вносити будь-які зміни до документації BeeWare, варто переконатися, що ви можете зібрати існуючу документацію.
Перш ніж приступити до створення документації, налаштуйте середовище розробки.
У вас обов'язково має бути встановлений інтерпретатор Python 3.13, який має бути доступний у шляху (тобто python3.13 має запускати інтерпретатор Python 3.13).
BeeWare використовує tox для створення документації. Наведені нижче команди tox необхідно виконувати з того самого каталогу, що й файл tox.ini, який знаходиться в кореневому каталозі проєкту.
Попередній перегляд документації в режимі реального часу¶
Для зручності швидкого редагування документації BeeWare має режим «попереднього перегляду в режимі реального часу».
Попередній перегляд у режимі реального часу буде сформовано з попередженнями!
Сервер у режимі реального часу доступний для ітеративного оновлення вашої документації. Під час оновлення ви можете допустити помилку в розмітці. Проблеми, позначені як WARNING, призведуть до збою стандартної збірки, однак робочий сервер налаштований так, що під час продовження збірки у консолі відображаються попередження. Це дозволяє вам вносити зміни без необхідності перезапуску попереднього перегляду.
WARNING відрізняється від ERROR. Якщо ви створите проблему, яка вважається ERROR, робочий сервер вийде з ладу і потребуватиме перезапуску. Він не запуститься знову, доки проблема ERROR не буде вирішена.
Щоб запустити сервер у режимі реального часу:
(venv) $ tox -e docs-live
(venv) $ tox -e docs-live
(venv) C:\...>tox -e docs-live
Це дозволить скомпілювати документацію, запустити веб-сервер для її розміщення та відстежувати зміни у файловій системі, пов’язані з вихідним кодом документації.
Після запуску сервера у виведенні консолі ви побачите щось на зразок такого:
ІНФО - [11:18:51] Обслуговування на http://127.0.0.1:8000/
Відкрийте браузер і перейдіть за вказаним URL-адресою. Тепер ви можете розпочати роботу з документацією. У разі виявлення змін документація буде перекомпільована, а всі браузери, що переглядають змінену сторінку, автоматично оновлюються.
docs-live — це перший крок
Запуск docs-live для роботи з робочим сервером призначений для початкового циклу розробки. Перед надсиланням запиту на злиття (pull request) вам слід завжди запускати локальну збірку.
Локальна збірка¶
Після завершення ітерації вам потрібно буде виконати локальну збірку документації. Цей процес збірки налаштований так, що у разі виявлення будь-яких проблем із розміткою він завершиться з помилкою. Це дозволяє виявити все, що ви, можливо, пропустили під час роботи на робочому сервері.
Створення локальної збірки¶
Щоб створити локальну збірку:
(venv) $ tox -e docs
(venv) $ tox -e docs
(venv) C:\...>tox -e docs
Результати цієї збірки будуть розміщені в каталозі _build у кореневому каталозі проєкту.
Створення локальної перекладеної збірки¶
Документація BeeWare перекладена на кілька мов. Оновлення англійської версії документації можуть спричинити проблеми в версіях іншими мовами. Перед надсиланням запиту на злиття важливо переконатися, що всі версії працюють належним чином.
Щоб створити збірку всіх доступних перекладів:
(дієслово) $ tox -e docs-all
(дієслово) $ tox -e docs-all
(venv) C:\...>tox -e docs-all
Результати компіляції кожної мовної версії будуть розміщені у відповідному каталозі _build/html/<languagecode>, де <languagecode> — це дво- або п’ятисимвольний код мови, пов’язаний із конкретною мовою (наприклад, fr для французької, it для італійської тощо).
Якщо ви виявили проблему з окремою збіркою, ви можете запустити цю збірку окремо, виконавши команду tox -e docs-<languagecode>. Наприклад, щоб зібрати лише французьку документацію, виконайте:
(venv) $ tox -e docs-fr
(venv) $ tox -e docs-fr
(venv) C:\...>tox -e docs-fr
Результати одномовного компілювання будуть розміщені в каталозі _build.
Перевірка документації на дотримання стилістичних правил¶
Процес збірки виявлятиме проблеми з Markdown, але BeeWare виконує деякі додаткові перевірки стилю та форматування, відомі як «лінтинг». Щоб запустити перевірки лінтингу:
(venv) $ tox -e docs-lint
(venv) $ tox -e docs-lint
(venv) C:\...>tox -e docs-lint
Це дозволить переконатися, що документація не містить:
- непрацюючі гіперпосилання
- слова з орфографічними помилками
Якщо правильне написання слова визнається помилковим, додайте це слово до списку в docs/spelling_wordlist. Таким чином слово буде додано до словника програми перевірки орфографії. Під час додавання до цього списку пам’ятайте:
- Ми віддаємо перевагу американській орфографії, допускаючи певні відхилення у вигляді специфічних для програмування розмовних слів (наприклад, «apps») та перетворення іменників на дієслова (наприклад, «scrollable»)
- У будь-якому згадуванні назви продукту слід дотримуватися рекомендованого способу написання з великої літери (наприклад, «macOS», «GTK», «pytest», «Pygame», «PyScript»).
- Якщо термін використовується «як код», його слід взяти в лапки як літерал (
like this), а не додавати до словника.
Після успішного створення документації ви готові до написання документації.