Руководство по документации

На этой странице описаны правила, которых следует придерживаться, если вы хотите внести свой вклад в Godot Engine создавая, проверяя или переводя его документацию. Помимо этих правил ознакомьтесь с файлом README в GitHub-репозитории godot-docs и с заглавной страницей этого сайта, чтобы узнать о том, какие шаги следует предпринять и как связаться с командой, работающей над документацией.

Как внести свой вклад

Создание или изменение страниц документации обычно осуществляется через GitHub-репозитории godot-docs. Страницы HTML (или документы PDF и EPUB) генерируется из файлов .rst (язык разметки reStructuredText), находящихся в этом репозитории. Изменение этих файлов с помощью Pull request и Merging вызовет изменение онлайн-документации.

См.также

Для получения подробной информации об использовании Git, в том числе - о механизме Pull request, обратитесь к странице Механизм Pull request. Большая часть того, что там сказано относительно основного репозитория godotengine/godot, также применимо и к репозиторию godotengine/godot-docs.

Файл README.md содержит всю информацию, необходимую для начала работы, поэтому пожалуйста, прочтите его. В частности, он содержит некоторые советы, рекомендации и ссылки на справочную информацию о языке разметки reStructuredText.

Предупреждение

Обратите внимание, что справочник Godot API нужно редактировать не в репозитории godot-docs. Вместо этого вам необходимо редактировать XML-файлы в каталоге doc/classes/* основного репозитория Godot. Эти файлы будут использованы для генерации как справки в редакторе Godot, так и веб-страниц в разделе Godot API. Подробнее читайте здесь: Contributing to the class reference.

Что делает документацию хорошей?

Документация должна быть написана грамотно, на простом языке, с использованием хорошо сформулированных и структурированных предложений. Она должна быть ясной и объективной. Кроме того, взгляните на Руководство по написанию документов.

Мы разделяем страницы-уроки и прочие страницы документации по следующим признакам:

  • урок (туториал): страница, предназначенная для объяснения того, как использовать одну или несколько концепций в редакторе или скриптах для решения конкретной задачи с целью обучения (примеры: "Создание простой 2D-игры в пинг-понг", "Применение сил к объекту");

  • документация: страница, в рамках которой описывается одна и только одна концепция - настолько исчерпывающе, насколько это возможно (примеры: "Список методов класса Sprite", "Обзор управления входными данными в Godot").

Вы можете писать любую документацию, какую пожелаете - при условии соблюдения правил, описанных здесь и в репозитории.

Заголовки

Всегда начинайте файл с имени-ссылки для Sphinx и заголовка страницы:

.. _doc_insert_your_title_here:

Insert your title here
======================

Первая строка позволяет инструменту Sphinx ссылаться на эту страницу в формате :ref:; например :ref:`doc_insert_your_title_here` будет ссылаться на приведённую выше страницу (обратите внимание на отсутствие начального подчёркивания в ссылке).

Кроме того, избегайте использования заголовков в стиле American CamelCase - первое слово заголовка должно начинаться с заглавной буквы, а каждое следующее слово - со строчной. Вот это хороший пример:

  • Подставьте ваш заголовок здесь

А это - плохой пример:

  • Подставьте Ваш Заголовок Здесь

Только имена собственные (названия проектов, имена людей) и наименования классов узлов должны начинаться с заглавной буквы.

Перевод существующих страниц

Вы можете помочь перевести официальную документацию Godot здесь: Hosted Weblate.

Translation state

Существует также официальный репозиторий godot-docs-l10n , где вы можете увидеть, когда данные были синхронизированы в последний раз.

Лицензия

Эта документация и каждая содержащаяся в ней страница публикуются в соответствии с условиями лицензии Creative Commons Attribution 3.0 (CC-BY 3.0), за авторством "Juan Linietsky, Ariel Manzur и сообщество Godot".

Внося свой вклад в документацию через GitHub репозиторий, вы соглашаетесь с тем, что ваши изменения распространяются в соответствии с настоящей лицензией.