Внески до документації

У цьому посібнику пояснюється, як зробити свій внесок у документацію Godot, будь то шляхом написання чи рецензування сторінок.

Дивись також

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

Перші кроки

Щоб змінити або створити сторінки в довідковому посібнику, вам потрібно відредагувати файли .rst у сховищі godot-docs GitHub. Зміна цих сторінок у запиті на витягування запускає перебудову онлайн-документації після злиття.

Дивись також

Докладні відомості про використання Git і робочий процес запиту на отримання дивіться на сторінці Робочий процес запиту на отримання. Більшість того, що в ньому описано щодо основного сховища godotengine/godot, також дійсне для сховища документів.

Попередження

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

Що таке документація Godot

Документація Godot призначена як вичерпний довідковий посібник для ігрового движка Godot. Він не міститиме покрокових посібників, за винятком двох посібників зі створення ігор у розділі «Початок роботи».

Ми прагнемо писати фактичний вміст доступною та добре написаною мовою. Щоб зробити свій внесок, ви також повинні прочитати:

  1. Інструкції з написання. Там ви знайдете правила та рекомендації писати так, щоб усі зрозуміли.

  2. Вказівки щодо змісту. Вони пояснюють принципи, яких ми дотримуємося під час написання документації, і тип вмісту, який ми приймаємо.

Внесення змін

За замовчуванням запити на отримання мають використовувати **головну гілку.** Виконуйте запити на отримання лише для інших гілок (наприклад, 3.6 або 4.2), якщо ваші зміни стосуються лише цієї версії Godot. Після того, як запит на отримання об’єднано в master, він зазвичай буде підібраний у поточну стабільну гілку розробниками документації.

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

Редагування існуючих сторінок

Щоб редагувати існуючу сторінку, знайдіть її вихідний файл .rst і відкрийте його у своєму улюбленому текстовому редакторі. Потім ви можете зафіксувати зміни, відправити їх у форк і зробити запит на отримання. Зверніть увагу, що сторінки в classes/ не слід редагувати тут. Вони автоматично генеруються з посилання на клас XML Godot. Перегляньте Внесок у довідку про клас для деталей.

Дивись також

Щоб створити посібник і протестувати зміни на своєму комп’ютері, перегляньте Складання посібника зі Sphinx.

Редагування сторінок онлай

Ви можете редагувати документацію онлайн, натиснувши посилання Редагувати на GitHub у верхньому правому куті кожної сторінки.

Ви перейдете до текстового редактора GitHub. Вам потрібно мати обліковий запис GitHub і ввійти, щоб використовувати його. Увійшовши в систему, ви можете запропонувати зміни таким чином:

  1. Натисніть кнопку Редагувати на GitHub.

  2. На сторінці GitHub, на яку ви потрапили, переконайтеся, що поточна гілка — «master». Натисніть піктограму олівця у верхньому правому куті біля кнопок Необроблено, Звинуватити та Видалити. Він має спливаючу підказку «Форкувати цей проект і редагувати файл».

  3. Відредагуйте текст у текстовому редакторі.

  4. Натисніть «Зафіксувати зміни...», підсумуйте внесені зміни та обов’язково замініть покажчик місця заповнення «Оновити файл.rst» коротким, але чітким однорядковим описом, оскільки це заголовок фіксації. Натисніть кнопку Запропонувати зміни.

  5. На наступних екранах натискайте кнопку Створити запит на отримання, доки не побачите повідомлення на кшталт Ім’я користувача хоче об’єднати 1 комміт у godotengine:master із імені користувача:patch-1.

Примітка

Якщо в запиті на отримання більше комітів, ніж ваших власних, ймовірно, ваша гілка була створена з використанням неправильного джерела, оскільки «master» не є поточною гілкою на кроці 2. Вам потрібно буде змінити базу гілки на «master» або створити нову гілку.

Інший учасник перегляне ваші зміни та об’єднає їх у документи, якщо вони прийнятні. Вони також можуть внести зміни або попросити вас зробити це перед об’єднанням.

Додавання нових сторінок

Перш ніж додавати нову сторінку, переконайтеся, що вона відповідає документації:

  1. Знайдіть існуючі проблеми або відкрийте нову, щоб перевірити, чи потрібна сторінка.

  2. Переконайтеся, що немає сторінки, яка б уже охоплювала цю тему.

  3. Прочитайте наші Вказівки щодо змісту.

Щоб додати нову сторінку, створіть файл .rst зі змістовною назвою в розділі, до якого ви хочете додати файл, наприклад. tutorials/3d/light_baking.rst.

Потім вам слід додати свою сторінку до відповідного "toctree" (змісту, наприклад tutorials/3d/index.rst). Додайте нову назву файлу до списку в новому рядку, використовуючи відносний шлях і без розширення, напр.  тут light_baking.

<b>Заголовки</b>

Завжди починайте сторінки з заголовка та посилання на Sphinx:

.. _doc_insert_your_title_here:

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

Посилання _doc_insert_your_title_here і назва мають збігатися.

Посилання дозволяє посилатися на цю сторінку за допомогою :ref: format, e.g. :ref:`doc_insert_your_title_here` буде посилатися на наведену вище сторінку прикладу (зверніть увагу на відсутність початкового підкреслення в посиланні).

Напишіть заголовки як прості речення, не пишучи кожне слово з великої літери:

  • Напишіть заголовки як прості речення, не пишучи кожне слово з великої літери

  • Погано: Розуміння сигналів у Godot

Лише власні іменники, проекти, люди та назви класів вузлів повинні мати першу літеру з великої літери.

Синтаксис Sphinx і reStructuredText

Перегляньте reST Primer Sphinx та офіційне посилання для детальної інформації про синтаксис.

Sphinx використовує спеціальні коментарі reST для виконання певних операцій, як-от визначення змісту (.. toctree::) або перехресних посилань на сторінки. Щоб дізнатися більше, перегляньте офіційну документацію Sphinx. Щоб дізнатися, як використовувати директиви Sphinx, такі як .. note:: або .. seealso::, перегляньте документацію щодо директив Sphinx.

Додавання зображень і вкладень

Щоб додати зображення, помістіть їх у папку img/ поруч із файлом .rst зі змістовною назвою та додайте їх на свою сторінку за допомогою:

.. image:: img/image_name.webp

Крім того, ви можете використовувати директиву figure, яка надає зображенню контрастну рамку та дозволяє розмістити його по центру сторінки.

.. figure:: img/image_name.webp
    :align: center

Ви також можете додати вкладення як допоміжний матеріал для підручника, розмістивши їх у папці files/ поруч із .rst файлом і використовуючи цю вбудовану розмітку:

:download:`file_name.zip <files/file_name.zip>`

Розгляньте можливість використання репозиторію godot-docs-project-starters <https://github.com/godotengine/godot-docs-project-starters> для розміщення допоміжних матеріалів, таких як шаблони проектів і пакети ресурсів. Ви можете використовувати пряме посилання на створений архів із цього сховища за допомогою звичайної розмітки посилань:

`file_name.zip <https://github.com/godotengine/godot-docs-project-starters/releases/download/latest-4.x/file_name.zip>`_

Ліцензія

Ця документація та кожна сторінка, що в ній міститься, опубліковані згідно з умовами ліцензії «Creative Commons Attribution 3.0 (CC BY 3.0) із посиланням на «Juan Linietsky». , Аріель Манзур і спільнота Godot».

Надаючи внесок у документацію в сховищі GitHub, ви погоджуєтесь, що ваші зміни поширюються за цією ліцензією.