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

На этой странице описаны правила, которых следует придерживаться, если вы хотите внести свой вклад в 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.

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

The class reference's source files are in the Godot engine repository. We generate the Godot API section of this documentation from them. If you want to update the description of a class, its methods, or properties, read Внесение вклада в справочник классов.

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

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

Ссылка 'Edit on GitHub'

Если вы читаете эту документацию на сайте docs.godotengine.org, то вы можете увидеть гиперссылку Edit на GitHub в правом верхнем углу страницы (примечание переводчика: это работает только для англоязычных страниц). При условии, что у вас есть учётная запись GitHub, вы можете предложить изменения для страницы, которую читаете, следующим образом:

1. Нажмите кнопку Редактировать на GitHub.

2. На странице GitHub, на которую вы попали, нажмите на значок карандаша в правом верхнем углу рядом с кнопками Raw, Blame и History. Он имеет всплывающую подсказку "Редактировать файл в форке этого проекта".

3. Завершите все правки, которые вы хотите сделать для этой страницы.

4. Обобщите внесенные изменения в форме внизу страницы и нажмите кнопку с надписью Предложить изменение файла, когда закончите.

5. На следующих экранах нажимайте кнопку Create pull request, пока не увидите сообщение типа Имя пользователя хочет объединить 1 коммит в godotengine:master из Username:patch-6.

6. рецензент оценит ваши изменения и, если они приемлемы, включит их в документацию; вас также могут попросить исправить что-то в вашем предложении, прежде чем принять его.

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

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

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

• Учебное пособие: страница, предназначенная для объяснения того, как использовать одну или несколько концепций в редакторе или скриптах для достижения конкретной цели с целью обучения (например, «Создание простой игры в 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.

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

Лицензия

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

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