Посприяйте документуванню Weblate

Будемо раді вашій участі в удосконаленні будь-яких сторінок документації. Зробити це просто: натисніть кнопку Редагувати на GitHub у верхньому правому куті вибраної сторінки.

Інструкції з документації

Будь ласка, дотримуйтеся таких настанов під час написання тексту:

  1. Не вилучайте частини документації, якщо вона є чинною.

  2. Користуйтеся чіткою і зрозумілою мовою. Ви пишете технічну документацію, не поему. Не усі читачі документації володіють англійською, будьте уважні.

  3. Не бійтеся спитати, якщо щось не зрозуміло. Якщо ви запитали про якусь можливість під час редагування, не змінюйте документацію щодо неї, доки не отримаєте відповіді. Це означає: або змінюйте, або питайте. Не виконуйте обидві дії одночасно.

  4. Перевіряйте ваші зміни, виконуючи описані дії відповідно до документації.

  5. Надсилайте запити щодо об’єднання малими фрагментами, щоб спростити і пришвидшити їхнє рецензування та злиття до сховища.

  6. Якщо вам хочеться переписати або змінити структуру великого розділу, робіть це у два кроки:

    1. Переписування

    2. Щойно переписування буде рецензовано, виправлено та злито до сховища, змініть структуру абзаців в іншому запиті щодо об’єднання.

Створення документації на місці

Документацію також можна редагувати та компілювати локально; вимоги до Python містяться у групі залежностей docs у файлі pyproject.toml. Якщо ви вже використовуєте повне середовище розробки, достатньо виконати команду uv sync --all-extras --dev. Якщо ви працюєте виключно з документацією, достатньо виконати команду uv sync --group docs.

Рекомендований локальний робочий процес такий:

make -C docs update-docs
./ci/run-docs

Оболонка ci/run-docs створює документацію, трактуючи попередження як помилки.

Підказка

Вам також знадобиться встановити graphviz для створення документації.

Переклад документації

Ви можете перекласти документацію.

Оновлення згенерованих фрагментів документації

У деяких розділах документації використовуються шаблони, згенеровані на основі коду. Найкращий спосіб їх оновлення:

make -C docs update-docs

Цей об’єкт оновлює фрагменти, які наразі використовуються в документації, зокрема:

  • додаткові події, вбудовані додатки та загальні параметри додатків

  • послуги машинного перекладу

  • параметри формату файлів та таблиці функцій формату файлів

  • права доступу та вбудовані ролі

  • чеки та прапорці

Текст, який оновлюється вручну, слід розміщувати на батьківській сторінці документації, а не додавати до автоматично згенерованих фрагментів. Наприклад, Додатки містить три згенеровані файли для подій, вбудованих додатків та загальних параметрів додатків, тоді як застарілі додатки оновлюються безпосередньо на цій сторінці.

Якщо вам потрібно оновити лише одну частину, окремі команди управління описано в Команди керування, а точні команди, які використовує update-docs, наведено у файлі docs/Makefile.