From 28b2b4fa937d88f62d087801d8e8f6d4816acd8f Mon Sep 17 00:00:00 2001 From: Lukas Tenbrink Date: Wed, 30 Jul 2025 01:13:56 +0200 Subject: [PATCH] Add documentation and class reference articles. --- documentation/class_reference.rst | 115 ++++++++++ documentation/documentation.rst | 215 ++++++++++++++++++ .../{first_steps.rst => overview.rst} | 4 +- index.rst | 4 +- 4 files changed, 335 insertions(+), 3 deletions(-) create mode 100644 documentation/class_reference.rst create mode 100644 documentation/documentation.rst rename documentation/{first_steps.rst => overview.rst} (96%) diff --git a/documentation/class_reference.rst b/documentation/class_reference.rst new file mode 100644 index 0000000..f06d223 --- /dev/null +++ b/documentation/class_reference.rst @@ -0,0 +1,115 @@ +.. _doc_updating_the_class_reference: + +Contributing to the class reference +=================================== + +.. highlight:: shell + +The :ref:`Class reference ` is a set of articles describing +the public API of the engine. This includes descriptions for various classes, +methods, properties, and global objects, available for scripting. The class reference +is available online, from the documentation sidebar, and in the Godot editor, from +the help menu. + +As the engine grows and features are added or modified, some parts of the class +reference become obsolete and new descriptions and examples need to be added. +While developers are required to document their work in the class reference when +submitting a pull request, we can't expect every programmer to be a good +technical writer. There is always work for contributors like you to polish +existing and create missing reference material. + +The source of the class reference +--------------------------------- + +As the class reference is available in two places, online and in the editor, we need to +take care to keep things in sync. To achieve this the `main Godot repository `_ +is picked as the source of truth, and the documentation for the class reference is tracked there. + +.. warning:: + + You should **not** edit ``.rst`` files in the ``classes/`` folder of the + `documentation repository `_. + These files are generated automatically and are synced manually by project + maintainers. Read further to learn how to correctly edit the class reference. + +In the main repository the class reference is stored in XML files, one for each exposed +class or global object. The majority of these files is located in `doc/classes/ +`_, but some modules +contain their own documentation as well. You will find it in the ``modules//doc_classes/`` +directory. To learn more about editing XML files refer to :ref:`doc_class_reference_primer`. + +.. seealso:: + + For details on Git usage and the pull request workflow, please + refer to the :ref:`doc_pr_workflow` page. + + If you want to translate the class reference from English to another + language, see :ref:`doc_editor_and_docs_localization`. This guide is + also available as a `video tutorial on YouTube + `_. + +**Important:** If you plan to make large changes, you should create an issue on +the `godot-docs repository `_ +or comment on an existing issue. Doing so lets others know you're already +taking care of a given class. + +What to contribute +------------------ + +The natural place to start contributing is the classes that you are most familiar with. +This ensures that the added description will be based on experience and the necessary +know-how, not just the name of a method or a property. We advise not to add low effort +descriptions, no matter how appealing it may look. Such descriptions obscure the need +for documentation and are hard to identify automatically. + +.. seealso:: + + Following this principle is important and allows us to create tools for contributors. + Such as the class reference's `completion status tracker `_. + You can use it to quickly find documentation pages missing descriptions. + +If you decide to document a class, but don't know what a particular method does, don't +worry. Leave it for now, and list the methods you skipped when you open a pull request +with your changes. Another writer will take care of it. + +You can still look at the method's implementation in Godot's source code on GitHub. +If you have doubts, feel free to ask on the `Godot Forum `_ +and `Godot Contributors Chat `_. + +.. warning:: + + Unless you make minor changes, like fixing a typo, we do not recommend using the + GitHub web editor to edit the class reference's XML files. It lacks features to edit + XML well, like keeping indentations consistent, and it does not allow amending commits + based on reviews. + + It also doesn't allow you to test your changes in the engine or with validation + scripts as described in :ref:`doc_class_reference_editing_xml`. + + +Updating class reference when working on the engine +--------------------------------------------------- + +When you create a new class or modify an existing engine's API, you need to re-generate +the XML files in ``doc/classes/``. + +To do so, you first need to compile Godot. See the :ref:`doc_introduction_to_the_buildsystem` +page to learn how. Then, execute the compiled Godot binary from the Godot root directory +with the ``--doctool`` option. For example, if you're on 64-bit Linux, the command might be: + +:: + + ./bin/godot.linuxbsd.editor.x86_64 --doctool + +The exact set of suffixes may be different. Carefully read through the linked article to +learn more about that. + +The XML files in ``doc/classes/`` should then be up-to-date with current Godot Engine +features. You can then check what changed using the ``git diff`` command. + +Please only include changes that are relevant to your work on the API in your commits. +You can discard changes in other XML files using ``git checkout``, but consider reporting +if you notice unrelated files being updated. Ideally, running this command should only +bring up the changes that you yourself have made. + +You will then need to add descriptions to any newly generated entries. diff --git a/documentation/documentation.rst b/documentation/documentation.rst new file mode 100644 index 0000000..e366698 --- /dev/null +++ b/documentation/documentation.rst @@ -0,0 +1,215 @@ +.. _doc_contributing_to_the_documentation: + +Contributing to the documentation +================================= + +This guide explains how to contribute to Godot's documentation, be it by +writing or reviewing pages. + +.. seealso:: + + If you want to translate pages or the class reference from English to other + languages, read :ref:`doc_editor_and_docs_localization`. + +Getting started +--------------- + +To modify or create pages in the reference manual, you need to edit ``.rst`` +files in the `godot-docs GitHub repository +`_. Modifying those pages in a pull +request triggers a rebuild of the online documentation upon merging. + +.. seealso:: For details on Git usage and the pull request workflow, please + refer to the :ref:`doc_pr_workflow` page. Most of what it describes + regarding the main godotengine/godot repository is also valid for + the docs repository. + +.. warning:: The class reference's source files are in the `Godot engine + repository `_. We generate + the :ref:`Class Reference ` section of this documentation + from them. If you want to update the description of a class, its + methods, or properties, read + :ref:`doc_updating_the_class_reference`. + +What is the Godot documentation +------------------------------- + +The Godot documentation is intended as a comprehensive reference manual for the +Godot game engine. It is not meant to contain step-by-step tutorials, except for +two game creation tutorials in the Getting Started section. + +We strive to write factual content in an accessible and well-written language. To +contribute, you should also read: + +1. :ref:`doc_docs_writing_guidelines`. There, you will find rules and + recommendations to write in a way that everyone understands. +2. :ref:`doc_content_guidelines`. They explain the principles we follow to write the + documentation and the kind of content we accept. + +Contributing changes +-------------------- + +**Pull requests should use the** ``master`` **branch by default.** Only make pull +requests against other branches (e.g. ``3.6`` or ``4.2``) if your changes only +apply to that specific version of Godot. After a pull request is merged into +``master``, it will usually be cherry-picked into the current stable branch by +documentation maintainers. + +Though less convenient to edit than a wiki, this Git repository is where we +write the documentation. Having direct access to the source files in a revision +control system is a plus to ensure our documentation quality. + +Editing existing pages +~~~~~~~~~~~~~~~~~~~~~~ + +To edit an existing page, locate its ``.rst`` source file and open it in your +favorite text editor. You can then commit the changes, push them to your fork, +and make a pull request. **Note that the pages in** ``classes/`` **should not be +edited here.** They are automatically generated from Godot's `XML class +reference `__. +See :ref:`doc_updating_the_class_reference` for details. + +.. seealso:: To build the manual and test changes on your computer, see + :ref:`doc_building_the_manual`. + +Editing pages online +-------------------- + +You can edit the documentation online by clicking the **Edit on GitHub** link in +the top-right of every page. + +Doing so takes you to the GitHub text editor. You need to have a GitHub account +and to log in to use it. Once logged in, you can propose change like so: + +1. Click the **Edit on GitHub** button. + +2. On the GitHub page you're taken to, make sure the current branch is "master". + Click the pencil icon in the top-right corner + near the **Raw**, **Blame**, and **Delete** buttons. + It has the tooltip "Fork this project and edit the file". + +3. Edit the text in the text editor. + +4. Click "Commit changes...", summarize the changes you made + and make sure to replace the placeholder "Update file.rst" by a short, + but clear one-line description, as this is the commit title. + Click the button **Propose changes**. + +5. On the following screens, click the **Create pull request** button until you + see a message like *Username wants to merge 1 commit into godotengine:master + from Username:patch-1*. + +.. note:: + + If there are more commits than your own in the pull request + it is likely that your branch was created using the wrong origin, + due to "master" not being the current branch in step 2. + You will need to rebase your branch to "master" or create a new branch. + +Another contributor will review your changes and merge them into the docs if +they're good. They may also make changes or ask you to do so before merging. + +Adding new pages +---------------- + +Before adding a new page, please ensure that it fits in the documentation: + +1. Look for `existing issues + `_ or open a new one to see + if the page is necessary. +2. Ensure there isn't a page that already covers the topic. +3. Read our :ref:`doc_content_guidelines`. + +To add a new page, create a ``.rst`` file with a meaningful name in the section you +want to add a file to, e.g. ``tutorials/3d/light_baking.rst``. + +You should then add your page to the relevant "toctree" (table of contents, +e.g. ``tutorials/3d/index.rst``). Add your new filename to the list on a new +line, using a relative path and no extension, e.g. here ``light_baking``. + +Titles +~~~~~~ + +Always begin pages with their title and a Sphinx reference name: + +:: + + .. _doc_insert_your_title_here: + + Insert your title here + ====================== + +The reference ``_doc_insert_your_title_here`` and the title should match. + +The reference allows linking to this page using the ``:ref:`` format, e.g. +``:ref:`doc_insert_your_title_here``` would link to the above example page (note +the lack of leading underscore in the reference). + +Write your titles like plain sentences, without capitalizing each word: + +- **Good:** Understanding signals in Godot +- **Bad:** Understanding Signals In Godot + +Only proper nouns, projects, people, and node class names should have their +first letter capitalized. + +Sphinx and reStructuredText syntax +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Check Sphinx's `reST Primer `__ +and the `official reference `__ for +details on the syntax. + +Sphinx uses specific reST comments to do specific operations, like defining the +table of contents (``.. toctree::``) or cross-referencing pages. Check the +`official Sphinx documentation +`__ for more details. To learn +how to use Sphinx directives like ``.. note::`` or ``.. seealso::``, check out +the `Sphinx directives documentation +`__. + +Adding images and attachments +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To add images, please put them in an ``img/`` folder next to the ``.rst`` file with +a meaningful name and include them in your page with: + +.. code:: rst + + .. image:: img/image_name.webp + +Alternatively, you can use the `figure` directive, which gives the image a contrasting +border and allows centering it on the page. + +.. code:: rst + + .. figure:: img/image_name.webp + :align: center + +You can also include attachments as support material for a tutorial, by placing them +into a ``files/`` folder next to the ``.rst`` file, and using this inline markup: + +.. code:: rst + + :download:`file_name.zip ` + +Consider using the `godot-docs-project-starters ` +repository for hosting support materials, such as project templates and asset packs. +You can use a direct link to the generated archive from that repository with the regular +link markup: + +.. code:: rst + + `file_name.zip `_ + + +License +------- + +This documentation and every page it contains is published under the terms of +the `Creative Commons Attribution 3.0 license (CC BY 3.0) +`_, with attribution to "Juan +Linietsky, Ariel Manzur and the Godot community". + +By contributing to the documentation on the GitHub repository, you agree that +your changes are distributed under this license. diff --git a/documentation/first_steps.rst b/documentation/overview.rst similarity index 96% rename from documentation/first_steps.rst rename to documentation/overview.rst index 3bd1b56..91acb96 100644 --- a/documentation/first_steps.rst +++ b/documentation/overview.rst @@ -1,5 +1,5 @@ -Getting started -=============== +Overview +======== There are two separate resources referred to as "documentation" in Godot: diff --git a/index.rst b/index.rst index f2d52f4..ce9c1a6 100644 --- a/index.rst +++ b/index.rst @@ -26,7 +26,9 @@ TODO :caption: Contributing documentation :name: sec-engine - documentation/first_steps + documentation/overview + documentation/class_reference + documentation/documentation documentation/translation .. toctree::