Внести вклад в документацию Weblate¶
Вы можете улучшить страницу документации по своему усмотрению. Сделать это легко, нажав на кнопку Редактировать на GitHub в правом верхнем углу страницы.
Рекомендации по документированию¶
Пожалуйста, соблюдайте эти рекомендации при написании:
Не удаляйте часть документации, если она действительна.
Используйте ясный и понятный язык. Вы пишете техническую документацию, а не поэму. Не все читатели документации являются носителями языка, будьте внимательны.
Не бойтесь задавать вопросы, если в чём-то не уверены. Если вопрос появился во время редактирования, не меняйте документацию, пока не получите ответ. Это значит, вы либо меняете, либо спрашиваете. Не делайте и то, и другое одновременно.
Проверьте свои изменения, выполнив описанные действия в соответствии с документацией.
Отправляйте запрос на извлечение(pull request) с изменениями небольшими частями, чтобы облегчить и ускорить их рассмотрение и объединение.
Если вы хотите переписать и изменить структуру большой статьи, сделайте это в два этапа:
Переписать
После того как изменённый вариант будет просмотрен, отшлифован и объединён, измените структуру абзацев в другом запросе на извлечение(pull request).
Building the documentation locally¶
Documentation can be also edited and built locally, the Python requirements are
in the docs dependency group in pyproject.toml. If you already use
the full development environment, uv sync --all-extras --dev is enough. For
documentation work only, uv sync --group docs is sufficient.
The recommended local workflow is:
make -C docs update-docs
./ci/run-docs
The ci/run-docs wrapper builds the documentation with warnings treated as errors.
Подсказка
You will also need graphviz installed to build the documentation.
Translating the documentation¶
Вы можете перевести документацию.
Updating generated documentation snippets¶
Several documentation sections use templates generated from the code. The preferred way to refresh them is:
make -C docs update-docs
This target regenerates the snippets currently used by the documentation, including:
add-on events, built-in add-ons, and common add-on parameters
machine translation services
file format parameters and file format feature tables
permissions and built-in roles
checks and check flags
Keep manually maintained text in the parent documentation page rather than adding it to autogenerated snippets. For example, Дополнения includes three generated files for events, built-in add-ons, and common add-on parameters, while obsolete add-ons are maintained directly in the page.
If you need to regenerate only one part, the individual management commands are
documented in Команды управления, and the exact commands used by
update-docs are listed in docs/Makefile.