Внести вклад в документацию Weblate¶
Вы можете улучшить страницу документации по своему усмотрению. Сделать это легко, нажав на кнопку Редактировать на GitHub в правом верхнем углу страницы.
Рекомендации по документированию¶
Пожалуйста, соблюдайте эти рекомендации при написании:
Не удаляйте часть документации, если она действительна.
Используйте ясный и понятный язык. Вы пишете техническую документацию, а не поэму. Не все читатели документации являются носителями языка, будьте внимательны.
Не бойтесь задавать вопросы, если в чём-то не уверены. Если вопрос появился во время редактирования, не меняйте документацию, пока не получите ответ. Это значит, вы либо меняете, либо спрашиваете. Не делайте и то, и другое одновременно.
Проверьте свои изменения, выполнив описанные действия в соответствии с документацией.
Отправляйте запрос на извлечение(pull request) с изменениями небольшими частями, чтобы облегчить и ускорить их рассмотрение и объединение.
Если вы хотите переписать и изменить структуру большой статьи, сделайте это в два этапа:
Переписать
После того как изменённый вариант будет просмотрен, отшлифован и объединён, измените структуру абзацев в другом запросе на извлечение(pull request).
Локальная сборка документации¶
Документацию также можно редактировать и собирать локально, требования 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.