Merge pull request #4067 from NathanLovato/content/writing-guidelines-updates

Update contribution guidelines

README.md

@@ -15,134 +15,20 @@ configuration, you can install the
 [Dark Website Forcer](https://addons.mozilla.org/en-US/firefox/addon/dark-mode-website-switcher/)
 add-on.
 
-## Contributing changes
+## Contributing
 
-If you'd like to contribute to the official documentation, whether you want to improve existing pages or write a new one, we would ask you to follow our workflow and guidelines:
+All contributors are welcome to help on the Godot documentation.
 
-1. If you want to write a new page, please start by opening an issue or join the discussion on an open issue with your proposal. This ensures that your work matches our [content guidelines](https://docs.godotengine.org/en/latest/community/contributing/content_guidelines.html) and saves everyone time.
-2. Before writing, be sure to check out our style guides:
-    - [Writing style guide](https://docs.godotengine.org/en/latest/community/contributing/docs_writing_guidelines.html)
-    - [GDScript style guide](https://docs.godotengine.org/en/latest/tutorials/scripting/gdscript/gdscript_styleguide.html) if you write GDScript code.
-    - [C# style guide](https://docs.godotengine.org/en/latest/tutorials/scripting/c_sharp/c_sharp_style_guide.html) if you write C# code.
+To get started, head to the [Contributing section](https://docs.godotengine.org/en/latest/community/contributing/index.html) of the online manual. There, you will find all the information you need to write and submit changes.
 
-We also detail how to create new pages on the documentation [here](https://docs.godotengine.org/en/latest/community/contributing/documentation_guidelines.html).
-
-**Pull Requests should use the `master` branch by default. Only make Pull Requests against other branches (e.g. `3.2` or `2.1`) if your changes only apply to that version of Godot.**
-
-### 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 references](https://github.com/godotengine/godot/tree/master/doc/classes).**
-See [Contribute to the Class Reference](https://docs.godotengine.org/en/latest/community/contributing/updating_the_class_reference.html) for details.
-
-### Adding new pages
-
-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`. Write its content like you would do for any other file, and make sure to define a reference name for Sphinx at the beginning of the file (check other files for the syntax), based on the file name with a "doc_" prefix (e.g. `.. _doc_light_baking:`).
-
-You should then add your page to the relevant "toctree" (table of contents, e.g. `tutorials/3d/index.rst`). By convention, the files used to define the various levels of toctree are prefixed with an underscore, so in the above example the file should be referenced in `tutorials/3d/_3d_graphics.rst`. Add your new filename to the list on a new line, using a relative path and no extension, e.g. here `light_baking`.
-
-### Sphinx and reStructuredText syntax
-
-Check Sphinx's [reST Primer](https://www.sphinx-doc.org/en/stable/rest.html) and the [official reference](http://docutils.sourceforge.net/rst.html) 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](https://www.sphinx-doc.org/en/stable/index.html) for more details, or see how things are done in existing pages and adapt it to your needs.
-
-### 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:
-```rst
-.. image:: img/image_name.png
-```
-
-Similarly, you can include attachments (like assets as support material for a tutorial) by placing them into a `files/` folder next to the .rst file, and using this inline markup:
-```rst
-:download:`myfilename.zip <files/myfilename.zip>`
-```
-
-## Building with Sphinx
-
-To build the HTML website (or any other format supported by Sphinx, like PDF, EPUB or LaTeX), you need to install [Sphinx](https://www.sphinx-doc.org/) >= 1.3 as well as (for the HTML) the [readthedocs.org theme](https://github.com/snide/sphinx_rtd_theme).
-You also need to install the Sphinx extensions defined in `requirements.txt`.
-
-Those tools are best installed using [pip](https://pip.pypa.io), Python's module installer. The Python 3 version might be provided (on Linux distros) as `pip3` or `python3-pip`. You can then run:
-
-```sh
-pip install -r requirements.txt
-```
-
-You can then build the HTML documentation from the root folder of this repository with:
-
-```sh
-make html
-```
-
-or:
-
-```sh
-make SPHINXBUILD=~/.local/bin/sphinx-build html
-```
-
-Building the documentation requires at least 8 GB of RAM to be done without swapping. If you have at least 16 GB of RAM, you can speed up compilation by using:
-
-```bash
-# On Linux/macOS
-make html SPHINXOPTS=-j2
-
-# On Windows
-set SPHINXOPTS=-j2 && make html
-```
-
-The compilation might take some time as the `classes/` folder contains many files to parse.
-
-In case of a `MemoryError` or `EOFError`, you can remove the `classes/` folder and run `make` again. This will drop the class references from the final HTML documentation but will keep the rest intact. Make sure to avoid using `git add .` in this case when working on a pull request, or the whole `classes/` folder will be removed when you make a commit. See [#3157](https://github.com/godotengine/godot-docs/issues/3157) for more details.
-
-You can then test the changes live by opening `_build/html/index.html` in your favorite browser.
-
-### Building with Sphinx on Windows
-
-On Windows, you need to:
-* Download the Python installer [here](https://www.python.org/downloads/).
-* Install Python. Don't forget to check the "Add Python to PATH" box.
-* Use the above `pip` commands.
-
-Building is still done at the root folder of this repository using the provided `make.bat`:
-```sh
-make.bat html
-```
-
-Alternatively, you can build with this command instead:
-```sh
-sphinx-build -b html ./ _build
-```
-
-Note that during the first build, various installation prompts may appear and ask to install LaTeX plugins.
-Make sure you don't miss them, especially if they open behind other windows, else the build may appear to hang until you confirm these prompts.
-
-You could also install a normal `make` toolchain (for example via MinGW) and build the docs using the normal `make html`.
-
-### Building with Sphinx and virtualenv
-
-If you want your Sphinx installation scoped to the project, you can install it using virtualenv.
-Execute this from the root folder of this repository:
-
-```sh
-virtualenv --system-site-packages env/
-. env/bin/activate
-pip install -r requirements.txt
-```
-
-Then do `make html` like above.
-
-### Rebuilding automatically on changes
-
-To build the documentation every time you save your changes, install
-[watchexec](https://github.com/watchexec/watchexec) then run the following
-command in this directory:
-
-```sh
-watchexec make html
-```
+Here are some quick links to the areas you might be interested in:
 
+1. [Contributing to the online manual](https://docs.godotengine.org/en/latest/community/contributing/contibuting_to_the_documentation.html)
+2. [Contributing to the class reference](https://docs.godotengine.org/en/latest/community/contributing/updating_the_class_reference.html)
+3. [Content guidelines](https://docs.godotengine.org/en/latest/community/contributing/content_guidelines.html)
+4. [Writing guidelines](https://docs.godotengine.org/en/latest/community/contributing/docs_writing_guidelines.html)
+5. [Translating the documentation](https://docs.godotengine.org/en/latest/community/contributing/editor_and_docs_localization.html)
+    
 ## License
 
 At the exception of the `classes/` folder, all the content of this repository is licensed under the Creative Commons Attribution 3.0 Unported license ([CC BY 3.0](https://creativecommons.org/licenses/by/3.0/)) and is to be attributed to "Juan Linietsky, Ariel Manzur and the Godot community".

about/introduction.rst

@@ -102,7 +102,7 @@ relatively intuitive:
   which is also available directly within the engine's script editor. It is
   generated automatically from a file in the main source repository, therefore
   the generated files of the documentation are not meant to be modified. See
-  :ref:`doc_updating_the_class_reference` for details.
+  :ref:`doc_class_reference_writing_guidelines` for details.
 
 In addition to this documentation you may also want to take a look at the
 various `Godot demo projects <https://github.com/godotengine/godot-demo-projects>`_.

community/contributing/building_the_manual.rst

@@ -0,0 +1,99 @@
+.. _doc_building_the_manual:
+
+Building the manual with Sphinx
+===============================
+
+This page explains how to build a local copy of the Godot manual using the
+Sphinx docs engine. This allows you to have local HTML files and build the
+documentation as a PDF, EPUB, or LaTeX file, for example.
+
+To get started, you need to:
+
+1. Clone the `godot-docs repository <https://github.com/godotengine/godot-docs/>`__.
+2. Install `Sphinx <https://www.sphinx-doc.org/>`__
+3. To build the docs as HTML files, install the `readthedocs.org theme
+   <https://github.com/snide/sphinx_rtd_theme>`__.
+4. Install the Sphinx extensions defined in the `godot-docs repository
+   <https://github.com/godotengine/godot-docs/>`__ ``requirements.txt`` file.
+
+We recommend using `pip <https://pip.pypa.io>` _, Python’s package manager to
+install all these tools. It comes pre-installed with `Python
+<https://www.python.org/>`__. Ensure that you install and use Python 3. Here are
+the commands to clone the repository and then install all requirements.
+
+.. code:: sh
+
+    git clone https://github.com/godotengine/godot-docs.git
+    pip install -r requirements.txt
+
+.. note:: On Linux distributions, you may need to write ``pip3`` instead of
+          ``pip`` because you generally have both Python 2 and 3 installed on
+          your system. Alternatively, you can explicitly ask Python 3 to execute
+          its version of pip as a module like so: ``python3 -m pip``.
+
+With the programs installed, you can build the HTML documentation from the root
+folder of this repository with the following command:
+
+.. code:: sh
+
+    # On Linux and MacOS
+    make html
+
+    # On Windows, you need to execute the ``make.bat`` file instead.
+    make.bat html
+
+If you run into errors, you may try the following command:
+
+.. code:: sh
+
+    make SPHINXBUILD=~/.local/bin/sphinx-build html
+
+Building the documentation requires at least 8 GB of RAM to run without disk
+swapping, which slows it down. If you have at least 16 GB of RAM, you can speed
+up compilation by running:
+
+.. code:: sh
+
+    # On Linux/macOS
+    make html SPHINXOPTS=-j2
+
+    # On Windows
+    set SPHINXOPTS=-j2 && make html
+
+The compilation will take some time as the ``classes/`` folder contains hundreds
+of files.
+
+You can then browse the documentation by opening ``_build/html/index.html`` in
+your web browser.
+
+In case you of a ``MemoryError`` or ``EOFError``, you can remove the
+``classes/`` folder and run ``make`` again. This will drop the class references
+from the final HTML documentation but will keep the rest intact.
+
+.. note:: If you delete the ``classes/`` folder, do not use ``git add .`` when
+          working on a pull request or the whole ``classes/`` folder will be
+          removed when you commit. See `#3157
+          <https://github.com/godotengine/godot-docs/issues/3157>`__ for more
+          detail.
+
+Alternatively, you can build the documentation by running the sphinx-build
+program manually:
+
+.. code:: sh
+
+   sphinx-build -b html ./ _build
+
+Building with Sphinx and virtualenv
+-----------------------------------
+
+If you want your Sphinx installation scoped to the project, you can install
+sphinx-build using virtualenv. To do so, run this command from this repository's
+root folder:
+
+.. code:: sh
+
+   virtualenv --system-site-packages env/
+   . env/bin/activate
+   pip install -r requirements.txt
+
+Then, run ``make html`` as shown above.

community/contributing/class_reference_writing_guidelines.rst

@@ -0,0 +1,254 @@
+.. _doc_class_reference_writing_guidelines:
+
+Class reference writing guidelines
+==================================
+
+This page explains how to write the class reference. You will learn where to
+write new descriptions for the classes, methods, and properties for Godot's
+built-in node types.
+
+.. seealso::
+
+    To learn to submit your changes to the Godot project using the Git version
+    control system, see :ref:`doc_updating_the_class_reference_with_git`.
+
+The reference for each class is contained in an XML file like the one below:
+
+.. code-block:: xml
+
+    <class name="Node2D" inherits="CanvasItem" version="4.0">
+        <brief_description>
+            A 2D game object, inherited by all 2D-related nodes. Has a position, rotation, scale, and Z index.
+        </brief_description>
+        <description>
+            A 2D game object, with a transform (position, rotation, and scale). All 2D nodes, including physics objects and sprites, inherit from Node2D. Use Node2D as a parent node to move, scale and rotate children in a 2D project. Also gives control of the node's render order.
+        </description>
+        <tutorials>
+            <link title="Custom drawing in 2D">https://docs.godotengine.org/en/latest/tutorials/2d/custom_drawing_in_2d.html</link>
+            <link title="All 2D Demos">https://github.com/godotengine/godot-demo-projects/tree/master/2d</link>
+        </tutorials>
+        <methods>
+            <method name="apply_scale">
+                <return type="void">
+                </return>
+                <argument index="0" name="ratio" type="Vector2">
+                </argument>
+                <description>
+                    Multiplies the current scale by the [code]ratio[/code] vector.
+                </description>
+            </method>
+            [...]
+            <method name="translate">
+                <return type="void">
+                </return>
+                <argument index="0" name="offset" type="Vector2">
+                </argument>
+                <description>
+                    Translates the node by the given [code]offset[/code] in local coordinates.
+                </description>
+            </method>
+        </methods>
+        <members>
+            <member name="global_position" type="Vector2" setter="set_global_position" getter="get_global_position">
+                Global position.
+            </member>
+            [...]
+            <member name="z_index" type="int" setter="set_z_index" getter="get_z_index" default="0">
+                Z index. Controls the order in which the nodes render. A node with a higher Z index will display in front of others.
+            </member>
+        </members>
+        <constants>
+        </constants>
+    </class>
+
+
+It starts with brief and long descriptions. In the generated docs, the brief
+description is always at the top of the page, while the long description lies
+below the list of methods, variables, and constants. You can find methods,
+member variables, constants, and signals in separate XML nodes.
+
+For each, you want to learn how they work in Godot's source code. Then, fill
+their documentation by completing or improving the text in these tags:
+
+- `<brief_description>`
+- `<description>`
+- `<constant>`
+- `<method>` (in its `<description>` tag; return types and arguments don't take separate
+  documentation strings)
+- `<member>`
+- `<signal>` (in its `<description>` tag; arguments don't take separate documentation strings)
+- `<constant>`
+
+Write in a clear and simple language. Always follow the :ref:`writing guidelines
+<doc_docs_writing_guidelines>` to keep your descriptions short and easy to read.
+**Do not leave empty lines** in the descriptions: each line in the XML file will
+result in a new paragraph, even if it is empty.
+
+.. _doc_class_reference_writing_guidelines_editing_xml:
+
+How to edit class XML
+---------------------
+
+Edit the file for your chosen class in ``doc/classes/`` to update the class
+reference. The folder contains an XML file for each class. The XML lists the
+constants and methods you will find in the class reference. Godot generates and
+updates the XML automatically.
+
+.. note:: For some modules in the engine's source code, you'll find the XML
+          files in the ``modules/<module_name>/doc_classes/`` directory instead.
+
+Edit it using your favorite text editor. If you use a code editor, make sure
+that it doesn't change the indent style: you should use tabs for the XML and
+four spaces inside BBCode-style blocks. More on that below.
+
+To check that the modifications you've made are correct in the generated
+documentation, navigate to the ``doc/`` folder and run the command ``make rst``.
+This will convert the XML files to the online documentation's format and output
+errors if anything's wrong.
+
+Alternatively, you can build Godot and open the modified page in the built-in
+code reference. To learn how to compile the engine, read the :ref:`compilation
+guide <toc-devel-compiling>`.
+
+We recommend using a code editor that supports XML files like Vim, Atom, Code,
+Notepad++, or another to comfortably edit the file. You can also use their
+search feature to find classes and properties quickly.
+
+.. _doc_class_reference_writing_guidelines_bbcode:
+
+Improve formatting with BBCode style tags
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Godot's class reference supports BBCode-like tags. They add nice formatting to
+the text. Here's the list of available tags:
+
++----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+
+| Tag                        | Effect                               | Usage                             | Result                                            |
++============================+======================================+===================================+===================================================+
+| [Class]                    | Link a class                         | Move the [Sprite].                | Move the :ref:`class_sprite`.                     |
++----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+
+| [method methodname]        | Link to a method in this class       | Call [method hide].               | See :ref:`hide <class_spatial_method_hide>`.      |
++----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+
+| [method Class.methodname]  | Link to another class's method       | Call [method Spatial.hide].       | See :ref:`hide <class_spatial_method_hide>`.      |
++----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+
+| [member membername]        | Link to a member in this class       | Get [member scale].               | Get :ref:`scale <class_node2d_property_scale>`.   |
++----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+
+| [member Class.membername]  | Link to another class's member       | Get [member Node2D.scale].        | Get :ref:`scale <class_node2d_property_scale>`.   |
++----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+
+| [signal signalname]        | Link to a signal in this class       | Emit [signal renamed].            | Emit :ref:`renamed <class_node_signal_renamed>`.  |
++----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+
+| [signal Class.signalname]  | Link to another class's signal       | Emit [signal Node.renamed].       | Emit :ref:`renamed <class_node_signal_renamed>`.  |
++----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+
+| [b] [/b]                   | Bold                                 | Some [b]bold[/b] text.            | Some **bold** text.                               |
++----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+
+| [i] [/i]                   | Italic                               | Some [i]italic[/i] text.          | Some *italic* text.                               |
++----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+
+| [code] [/code]             | Monospace                            | Some [code]monospace[/code] text. | Some ``monospace`` text.                          |
++----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+
+| [kbd] [/kbd]               | Keyboard/mouse shortcut              | Some [kbd]Ctrl + C[/kbd] key.     | Some :kbd:`Ctrl + C` key.                         |
++----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+
+| [codeblock] [/codeblock]   | Multiline preformatted block         | *See below.*                      | *See below.*                                      |
++----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+
+| [codeblocks] [/codeblocks] | [codeblock] for multiple languages   | *See below.*                      | *See below.*                                      |
++----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+
+| [gdscript] [/gdscript]     | GDScript codeblock tab in codeblocks | *See below.*                      | *See below.*                                      |
++----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+
+| [csharp] [/csharp]         | C# codeblock tab in codeblocks       | *See below.*                      | *See below.*                                      |
++----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+
+
+Use ``[codeblock]`` for pre-formatted code blocks. Inside ``[codeblock]``,
+always use **four spaces** for indentation. The parser will delete tabs. For
+example:
+
+.. code-block:: none
+
+    [codeblock]
+    func _ready():
+        var sprite = get_node("Sprite")
+        print(sprite.get_pos())
+    [/codeblock]
+
+Will display as:
+
+.. code-block:: gdscript
+
+    func _ready():
+        var sprite = get_node("Sprite")
+        print(sprite.get_pos())
+
+If you need to have different code version in GDScript and C#, use
+``[codeblocks]`` instead. If you use ``[codeblocks]``, you also need to have at
+least one of the language-specific tags, ``[gdscript]`` and ``[csharp]``.
+
+Always write GDScript code examples first! You can use this `experimental code
+translation tool <https://github.com/HaSa1002/codetranslator>`_ to speed up your
+workflow.
+
+.. code-block:: none
+
+    [codeblocks]
+    [gdscript]
+    func _ready():
+        var sprite = get_node("Sprite")
+        print(sprite.get_pos())
+    [/gdscript]
+    [csharp]
+    public override void _Ready()
+    {
+        var sprite = GetNode("Sprite");
+        GD.Print(sprite.GetPos());
+    }
+    [/csharp]
+    [/codeblocks]
+
+The above will display as:
+
+.. tabs::
+ .. code-tab:: gdscript GDScript
+
+    func _ready():
+        var sprite = get_node("Sprite")
+        print(sprite.get_pos())
+
+ .. code-tab:: csharp
+
+    public override void _Ready()
+    {
+        var sprite = GetNode("Sprite");
+        GD.Print(sprite.GetPos());
+    }
+
+To denote important information, add a paragraph starting with "[b]Note:[/b]" at
+the end of the description:
+
+.. code-block:: none
+
+    [b]Note:[/b] Only available when using the Vulkan renderer.
+
+To denote crucial information that could cause security issues or loss of data
+if not followed carefully, add a paragraph starting with "[b]Warning:[/b]" at
+the end of the description:
+
+.. code-block:: none
+
+    [b]Warning:[/b] If this property is set to [code]true[/code], it allows clients to execute arbitrary code on the server.
+
+For deprecated properties, add a paragraph starting with "[i]Deprecated.[/i]".
+Notice the use of italics instead of bold:
+
+.. code-block:: none
+
+    [i]Deprecated.[/i] This property has been replaced by [member other_property].
+
+In all the paragraphs described above, make sure the punctuation is part of the
+BBCode tags for consistency.
+
+I don't know what this method does!
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+No problem. Leave it behind, and list the methods you skipped when you request a
+pull of your changes. Another writer will take care of it.
+
+You can still look at the methods' implementation in Godot's source code on
+GitHub. If you have doubts, feel free to ask on the `Q&A website
+<https://godotengine.org/qa/>`__ and IRC (Freenode, #godotengine).

community/contributing/contributing_to_the_documentation.rst

@@ -0,0 +1,190 @@
+.. _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
+<https://github.com/godotengine/godot-docs>`_. 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 <https://github.com/godotengine/godot>`_. We generate
+             the :ref:`Godot API <toc-class-ref>` 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_with_git`.
+
+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. The :ref:`doc_docs_writing_guidelines`. There, you will find rules and
+   recommendations to write in a way that everyone understands.
+2. The 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. ``2.1`` or ``3.0``) if your changes only
+ apply to that specific version of Godot.
+
+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 <https://github.com/godotengine/godot/tree/master/doc/classes>`__.
+See `Contribute to the Class Reference
+<https://docs.godotengine.org/en/latest/community/contributing/updating_the_class_reference.html>`__
+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, 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. At the bottom of the web page, summarize the changes you made and click the
+   button **Propose file change**. Make sure to replace the placeholder "Update file.rst"
+   by a short but clear one-line description, as this is the commit title.
+
+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*.
+
+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
+   <https://github.com/godotengine/godot-docs/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 propers nouns, projects, people, and node class names should have their
+first letter capitalized.
+
+Sphinx and reStructuredText syntax
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Check Sphinx’s `reST Primer <https://www.sphinx-doc.org/en/stable/rest.html>`__
+and the `official reference <http://docutils.sourceforge.net/rst.html>`__ 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
+<https://www.sphinx-doc.org/en/stable/index.html>`__ for more details. To learn
+how to use Sphinx directives like ``.. note::`` or ``.. seealso::``, check out
+the `Sphinx directives documentation
+<https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html>`__.
+
+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.png
+
+Similarly, you can include attachments, like assets 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:`myfilename.zip <files/myfilename.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)
+<https://tldrlegal.com/license/creative-commons-attribution-(cc)>`_, 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.

community/contributing/documentation_guidelines.rst

@@ -1,139 +0,0 @@
-.. _doc_documentation_guidelines:
-
-Documentation guidelines
-========================
-
-This page describes the rules to follow if you want to contribute to Godot
-Engine by writing or reviewing documentation, or by translating existing
-documentation. Also, have a look at README of the
-`godot-docs GitHub repository <https://github.com/godotengine/godot-docs>`_
-and the `docs front page <https://docs.godotengine.org>`_
-on what steps to follow and how to contact the docs team.
-
-How to contribute
------------------
-
-Creating or modifying documentation pages is mainly done via the
-`godot-docs GitHub repository <https://github.com/godotengine/godot-docs>`_.
-The HTML (or PDF and EPUB) documentation is generated from the .rst files
-(reStructuredText markup language) in that repository. Modifying those pages
-in a pull request and getting it merged will trigger a rebuild of the online
-documentation.
-
-.. 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.
-
-The README.md file contains all the information you need to get you started,
-please read it. In particular, it contains some tips and tricks and links to
-reference documentation about the reStructuredText markup language.
-
-.. warning:: If you want to edit the **API reference**, please note that it
-             should *not* be done in the godot-docs repository. Instead, you
-             should edit the ``doc/classes/*`` XML files of Godot's
-             main repository. These files are then later used to generate the
-             in-editor documentation as well as the API reference of the
-             online docs. Read more here: :ref:`doc_updating_the_class_reference`.
-
-The 'Edit on GitHub' link
--------------------------
-
-If you're reading documentation on `docs.godotengine.org <https://docs.godotengine.org>`_,
-you'll see an **Edit on GitHub** hyperlink at the top right of the page.
-Once you've created a GitHub account, you can propose changes to a page you're
-reading as follows:
-
-1. Click the **Edit on GitHub** button.
-
-2. On the GitHub page you're taken to, click the pencil icon in the top-right
-   corner near the **Raw**, **Blame** and **History** buttons. It has the tooltip
-   "Edit the file in a fork of this project".
-
-3. Complete all the edits you want to make for that page.
-
-4. Summarize the changes you made in the form at the bottom of the page and
-   click the button labelled **Propose file change** when done.
-
-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-6*.
-
-6. A reviewer will evaluate your changes and incorporate them into the docs if
-   they're acceptable. You might also be asked to make
-   modifications to your changes before they're included.
-
-What makes good documentation?
-------------------------------
-
-Documentation should be well written in plain English, using well-formed
-sentences and various levels of sections and subsections. It should be clear
-and objective. Also, have a look at the :ref:`doc_docs_writing_guidelines`.
-
-We differentiate tutorial pages from other documentation pages by these
-definitions:
-
--  Tutorial: a page aiming at explaining how to use one or more concepts in
-   the editor or scripts in order to achieve a specific goal with a learning
-   purpose (e.g. "Making a simple 2d Pong game", "Applying forces to an
-   object").
--  Documentation: a page describing precisely one and only one concept at a
-   time, if possible exhaustively (e.g. the list of methods of the
-   Sprite class, or an overview of the input management in Godot).
-
-You are free to write the kind of documentation you wish, as long as you
-respect the following rules (and the ones on the repo).
-
-Titles
-------
-
-Always begin pages with their title and a Sphinx reference name:
-
-::
-
-    .. _doc_insert_your_title_here:
-
-    Insert your title here
-    ======================
-
-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).
-
-Also, avoid American CamelCase titles: title's first word should begin
-with a capitalized letter, and every following word should not. Thus,
-this is a good example:
-
--  Insert your title here
-
-And this is a bad example:
-
--  Insert Your Title Here
-
-Only project, people and node class names should have capitalized first
-letter.
-
-Translating existing pages
---------------------------
-
-You can help to translate the official Godot documentation on our `Hosted Weblate <https://hosted.weblate.org/engage/godot-engine/>`_.
-
-.. image:: https://hosted.weblate.org/widgets/godot-engine/-/godot-docs/287x66-white.png
-    :alt: Translation state
-    :align: center
-    :target: https://hosted.weblate.org/engage/godot-engine/?utm_source=widget
-    :width: 287
-    :height: 66
-
-There also is the official
-`Godot i18n repository <https://github.com/godotengine/godot-docs-l10n>`_
-where you can see when the data was last synchronized.
-
-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) <https://tldrlegal.com/license/creative-commons-attribution-(cc)>`_, 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.

community/contributing/editor_and_docs_localization.rst

@@ -324,7 +324,7 @@ breaks if they are not part of the original translation.
 .. seealso::
 
     See our documentation for class reference writers for the :ref:`list of
-    BBCode-like tags <doc_updating_the_class_reference_bbcode>` which are used
+    BBCode-like tags <doc_class_reference_writing_guidelines_bbcode>` which are used
     throughout the class reference.
 
 Offline translation and testing

community/contributing/index.rst

@@ -1,18 +1,106 @@
 Contributing
 ============
 
+Everyone is most welcome to contribute to Godot. Here are some ways in which you
+can contribute to the project:
+
+- Improving the engine by fixing bugs, coding new features, or refining existing ones.
+- Writing or proofreading documentation. You can contribute both to this
+  reference manual or the code reference.
+- Translating the editor or documentation from English to other languages.
+- Reporting issues or `writing detailed proposals
+  <https://github.com/godotengine/godot-proposals/>`__.
+
+Getting started
+---------------
+
+You would like to contribute but you don't know how or what to do? You can get
+answers below.
+
 .. toctree::
    :maxdepth: 1
-   :name: toc-community-contributing
+   :name: toc-community-getting-started
 
    ways_to_contribute
+
+.. _doc_community_contributing_to_the_engine:
+
+Contributing to the engine
+--------------------------
+
+The guides below explain how to contribute to the engine's core. You will learn
+about the code style, the contribution workflow, and more.
+
+.. toctree::
+   :maxdepth: 1
+   :name: toc-community-contributing-to-the-engine
+
    best_practices_for_engine_contributors
    pr_workflow
    bisecting_regressions
    code_style_guidelines
    bug_triage_guidelines
+
+.. _doc_community_writing_documentation:
+
+Writing documentation
+---------------------
+
+We always need help to improve the documentation, be it the class reference or
+the manual. Below, you can find our content and writing guidelines and
+concrete guides to make changes to the documentation.
+
+Guidelines
+~~~~~~~~~~
+
+Here are the principles and guidelines we strive to follow to write accessible
+documentation.
+
+.. toctree::
+   :maxdepth: 1
+   :name: toc-community-writing-guidelines
+
    content_guidelines
-   documentation_guidelines
    docs_writing_guidelines
+
+Writing the manual
+~~~~~~~~~~~~~~~~~~
+
+.. toctree::
+   :maxdepth: 1
+   :name: toc-community-documentation
+
+   contributing_to_the_documentation
+   building_the_manual
+
+Class reference guides
+~~~~~~~~~~~~~~~~~~~~~~
+
+The pages below focus on the class reference.
+
+As the reference is included in the Godot editor, its source files are part of
+the `godot repository <https://github.com/godotengine/godot>`_. We use XML files
+to write it, so the process to contribute to the class reference differs from
+writing the online manual.
+
+.. toctree::
+   :maxdepth: 1
+   :name: toc-community-class-reference
+
    updating_the_class_reference
+   class_reference_writing_guidelines
+
+.. _doc_community_translating_the_documentation:
+
+Translating the documentation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The community is always working hard on making Godot and its documentation
+available to more people. Localizing the documentation is a colossal and ongoing
+effort you can be part of.
+
+.. toctree::
+   :maxdepth: 1
+   :name: toc-community-localization
+
    editor_and_docs_localization

community/contributing/updating_the_class_reference.rst

@@ -1,57 +1,88 @@
-.. _doc_updating_the_class_reference:
+.. _doc_updating_the_class_reference_with_git:
 
-Contributing to the class reference
-===================================
+Contributing to the class reference with Git
+============================================
 
 .. highlight:: shell
 
-.. note:: This guide also is available as a `video tutorial on YouTube <https://www.youtube.com/watch?v=5jeHXxeX-JY>`_.
+This page gives you an overview of the steps to submit changes to Godot's class
+reference using the Git version control system.
 
-Godot ships with many nodes and singletons to help you develop your games. Each is a class, documented in the :ref:`class reference <toc-class-ref>`.
-This reference is essential for anyone learning the engine: it is available both online and in the engine.
+The class reference is available online in the :ref:`classes <toc-class-ref>`
+section of the documentation and in the Godot editor, from the help menu.
 
-But it's incomplete. Some methods, variables and signals lack descriptions. Others changed with recent releases and need updates.
-The developers can't write the entire reference on their own. Godot needs you, and all of us, to contribute.
+.. seealso::
+
+    This guide focuses on using Git. You can find the writing guidelines for the
+    class reference :ref:`here <doc_class_reference_writing_guidelines>`.
+
+    If you want to translate the class reference from English to another
+    language, see :ref:`doc_editor_and_docs_localization`.
 
-**Important:** If you are planning to make larger changes or a more substantial contribution, it is usually a good idea
-to create an issue (or a comment in an existing one) to let others know so they don't start working on the same thing too. Class
-reference issues should be opened in the `godot-docs repository <https://github.com/godotengine/godot-docs/issues>`__.
+In the class reference, some methods, variables, and signals lack descriptions.
+Others changed with recent releases and need updates. The developers can't write
+the entire reference on their own. Godot needs you, and all of us, to
+contribute.
+
+**Important:** If you plan to make large changes, you should create an issue on
+ the `godot-docs repository <https://github.com/godotengine/godot-docs/>`_
+ or comment on an existing issue. Doing so lets others know you're already
+ taking care of a given class.
 
 .. seealso::
 
-    Not sure where to start contributing? Take a look at the current class reference
+    Not sure which class to contribute to? Take a look at the class reference's
     completion status `here <https://godotengine.github.io/doc-status/>`__.
 
 How to contribute
 -----------------
 
-The class reference lies in the following XML files, in Godot's GitHub repository: `doc/classes/ <https://github.com/godotengine/godot/tree/master/doc/classes>`_.
+You can find the source files for the class reference in Godot's GitHub
+repository: `doc/classes/
+<https://github.com/godotengine/godot/tree/master/doc/classes>`_.
+
+.. note:: For some modules in the engine's source code, you'll find the XML
+          files in the ``modules/<module_name>/doc_classes/`` directory instead.
 
-There are 5 steps to update the class reference (full guide below):
+There are five steps to update the class reference:
 
 1. Fork `Godot's repository <https://github.com/godotengine/godot>`_
-2. Clone your fork on your computer
-3. Edit the class file in ``doc/classes/`` to write documentation
-4. Commit your changes and push them to your fork
-5. Make a pull request on the Godot repository
+2. Clone your fork on your computer.
+3. Edit the class file in ``doc/classes/`` to write documentation.
+4. Commit your changes and push them to your fork.
+5. Make a pull request on the Godot repository.
 
-.. warning:: Always use these XML files to edit the API reference. Do not edit the generated .rst files :ref:`in the online documentation <toc-class-ref>`, hosted in the `godot-docs <https://github.com/godotengine/godot-docs>`_ repository.
+You will find a complete breakdown of these steps below.
 
-Get started with GitHub
------------------------
+.. seealso:: This guide is also available as a `video tutorial on YouTube
+             <https://www.youtube.com/watch?v=5jeHXxeX-JY>`_.
 
-If you're new to Git and GitHub, this guide will help you get started. You'll learn to:
+.. warning:: Always edit the API reference through these source XML files. Do
+             not edit the generated ``.rst`` files :ref:`in the online documentation
+             <toc-class-ref>`, hosted in the `godot-docs
+             <https://github.com/godotengine/godot-docs>`_ repository.
+
+Getting started with GitHub
+---------------------------
+
+If you're new to using GitHub, the platform we use to develop Godot, this guide
+will help you get started. You will learn to:
 
 - Fork and clone Godot's repository
 - Keep your fork up to date with other contributors
-- Create a pull request so your improvements end in the official docs
+- Create a pull request to submit your improvements to the official docs
 
-.. note:: If you're new to Git, the version control system Godot uses, go through `GitHub's interactive guide <https://try.github.io/levels/1/challenges/1>`_. You'll learn some essential vocabulary and get a sense for the tool.
+.. note:: If you're new to Git, the version control system Godot uses, start
+          with `GitHub's interactive guide
+          <https://try.github.io/levels/1/challenges/1>`_. You'll learn some
+          essential vocabulary and get a sense for how the tool works.
 
-Fork Godot
-~~~~~~~~~~
+Forking Godot
+~~~~~~~~~~~~~
 
-Fork the Godot Engine into a GitHub repository of your own.
+Start by forking the Godot Engine into a GitHub repository of your own. Read the
+`GitHub forking guide <https://guides.github.com/activities/forking/>`_ to learn
+to create forks.
 
 Clone the repository on your computer:
 
@@ -59,93 +90,76 @@ Clone the repository on your computer:
 
     git clone https://github.com/your_name/godot.git
 
-Create a new branch to make your changes. It makes it a lot easier to sync your improvements with other docs writers. It's also easier to clean up your repository if you run into any issues with Git.
+Create a new branch to make your changes. It makes it a lot easier to
+synchronize your improvements with other contributors. It's also easier to clean
+up your repository if you run into any issues with Git.
 
 ::
 
     git checkout -b your-new-branch-name
 
-The new branch is the same as your master branch until you start to write API docs. In the ``doc/`` folder, you'll find the class reference.
+The new branch is the same as your master branch until you start to write API
+docs. You will find the class reference in the ``doc/classes/`` folder.
 
-How to keep your local clone up-to-date
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Keeping your local clone up-to-date
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Other writers contribute to Godot's documentation. Your local repository will fall behind it, and you'll have to synchronize it. Especially if other contributors update the class reference while you work on it.
+Other writers contribute to Godot's documentation. Your local repository will
+fall behind it. You will have to synchronize it, especially if other
+contributors update the class reference while you are working on it.
 
-First add an ``upstream`` git *remote* to work with. Remotes are links to online repositories you can download new files from.
+First, add an ``upstream`` Git *remote*. Remotes are links to online repositories
+from which you can download new files. The following command registers a new
+remote named "upstream" that links to the original Godot repository.
 
 ::
 
     git remote add upstream https://github.com/godotengine/godot
 
-You can check the list of all remote servers with:
-
-::
-
-    git remote -v
-
-You should have two: ``origin``, your fork on GitHub that Git adds by default, and ``upstream``, that you just added:
-
-
-::
-
-    origin  https://github.com/your_name/godot.git (fetch)
-    origin  https://github.com/your_name/godot.git (push)
-    upstream        https://github.com/godotengine/godot.git (fetch)
-    upstream        https://github.com/godotengine/godot.git (push)
-
-Each time you want to sync your branch to the state of the upstream repository, enter:
+Each time you want to synchronize your branch with the upstream repository,
+enter:
 
 ::
 
     git pull --rebase upstream master
 
-This command will first ``fetch``, or download the latest version of the Godot repository. Then, it will reapply your local changes on top.
+This command will first ``fetch``, that is, download the latest version of the
+Godot repository. Then, it will reapply your local changes on top of it.
 
-If you made changes you don't want to keep in your local branch, use the following commands instead:
+If you made changes you don't want to keep in your local branch, use the
+following commands instead:
 
 ::
 
     git fetch upstream
-    git reset --hard upstream master
+    git reset --hard upstream/master
 
-**Warning:** The above command will reset your branch to the state of the ``upstream master`` branch. It will discard all local changes. Make sure to only run this *before* you make important changes.
+**Warning:** The above command will reset your branch to the state of the
+ ``upstream/master`` branch. It will discard all local changes. Make sure to
+ only run this *before* you make important changes.
 
-Another option is to delete the branch you're working on, synchronize the master branch with the Godot repository, and create a new branch:
+Another option is to delete the branch you're working on, synchronize the master
+branch with the Godot repository, and create a new branch:
 
 ::
 
     git checkout master
-    git branch -d your-new-branch-name
     git pull --rebase upstream master
+    # Creates a new branch and checks out to it
     git checkout -b your-new-branch-name
 
-If you're feeling lost by now, come to our `IRC channels <https://webchat.freenode.net/?channels=#godotengine>`_ and ask for help. Experienced Git users will give you a hand.
-
-Updating the documentation template
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-When classes are modified in the source code, the documentation template might become outdated. To make sure that you are editing an up-to-date version, you first need to compile Godot (you can follow the :ref:`doc_introduction_to_the_buildsystem` page), and then run the following command (assuming 64-bit Linux):
-
-::
-
-    ./bin/godot.linuxbsd.tools.64 --doctool .
-
-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. If there are changes to other classes than the one you are planning to document, please commit those changes first before starting to edit the template:
-
-::
-
-    git add doc/classes/*.xml
-    git commit -m "Sync classes reference template with current code base"
+If you're feeling lost by now, come to our `IRC channels
+<https://webchat.freenode.net/?channels=#godotengine>`_ and ask for help.
+Experienced Git users will give you a hand.
 
-You are now ready to edit this file to add stuff.
+Alternatively, you can join the `Godot Discord server
+<https://discord.gg/4JBkykG>`_ and participate in the ``#documentation``
+channel.
 
-**Note:** If this has been done recently by another contributor, you don't forcefully need to go through these steps (unless you know that the class you plan to edit *has* been modified recently).
+Submitting your changes
+~~~~~~~~~~~~~~~~~~~~~~~
 
-Push and request a pull of your changes
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Once your modifications are finished, push your changes on your GitHub
+Once you finished modifying the reference, push your changes to your GitHub
 repository:
 
 ::
@@ -154,220 +168,37 @@ repository:
     git commit -m "Explain your modifications."
     git push
 
-When it's done, you can ask for a Pull Request via the GitHub UI of your Godot fork.
-
-.. warning::
+When it's done, you can ask for a pull request (abbreviated PR) on GitHub.
 
-    Although you can edit files on GitHub, it's not recommended. As hundreds of contributors work on Godot, the Git history must stay clean. Each commit should bundle all related improvements you make to the class reference, a new feature, bug fixes... When you edit from GitHub, it will create a new branch and a Pull Request every time you want to save it. If a few days pass before your changes get a review, you won't be able to update to the latest version of the repository cleanly. Also, it's harder to keep clean indents from GitHub. And they're very important in the docs.
-
-    TL;DR: If you don't know exactly what you're doing, do not edit files from GitHub.
-
-How to edit class XML
----------------------
-
-Edit the file for your chosen class in ``doc/classes/`` to update the class reference. The folder contains an XML file for each class. The XML lists the constants and methods you'll find in the class reference. Godot generates and updates the XML automatically.
-
-Edit it using your favorite text editor. If you use a code editor, make sure that it doesn't change the indent style: tabs for the XML, and 4 spaces inside BBCode-style blocks. More on that below.
-
-If you need to check that the modifications you've made are correct in the generated documentation, build Godot as described :ref:`here <toc-devel-compiling>`, run the editor and open the help for the page you modified.
-
-How to write the class reference
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Each class has a brief and long description. The brief description is always at the top of the page, while the full description lies below the list of methods, variables, and constants. Methods, member variables, constants, and signals are in separate categories or XML nodes. For each, learn how they work in Godot's source code, and fill their <description>.
-
-Our job is to add the missing text between these marks:
-
--  <description></description>
--  <brief_description></brief_description>
--  <constant></constant>
--  <method></method>
--  <member></member>
--  <signal></signal>
-
-Write using clear and simple language. Always follow the :ref:`writing guidelines <doc_docs_writing_guidelines>` to keep your descriptions short and easy to read. **Do not leave empty lines** in the descriptions: each line in the XML file will result in a new paragraph.
-
-Here's how a class looks like in XML:
-
-.. code-block:: xml
-
-    <class name="Node2D" inherits="CanvasItem" category="Core">
-        <brief_description>
-            Base node for 2D system.
-        </brief_description>
-        <description>
-            Base node for the 2D system. Node2D contains a position, rotation, and scale, which is used to position and animate. It can alternatively be used with a custom 2D transform ([Matrix32]). A tree of Node2Ds allows complex hierarchies for animation and positioning.
-        </description>
-        <methods>
-            <method name="set_pos">
-                <argument index="0" name="pos" type="Vector2">
-                </argument>
-                <description>
-                    Sets the position of the 2D node.
-                </description>
-            </method>
-            [...]
-            <method name="edit_set_pivot">
-                <argument index="0" name="arg0" type="Vector2">
-                </argument>
-                <description>
-                </description>
-            </method>
-        </methods>
-        <members>
-            <member name="global_position" type="Vector2" setter="set_global_position" getter="get_global_position" brief="">
-            </member>
-            [...]
-            <member name="z_as_relative" type="bool" setter="set_z_as_relative" getter="is_z_relative" brief="">
-            </member>
-        </members>
-        <constants>
-        </constants>
-    </class>
-
-
-Use a code editor like Vim, Atom, Code, Notepad++ or anything similar to edit the file quickly. Use the search function to find classes fast.
-
-.. _doc_updating_the_class_reference_bbcode:
-
-Improve formatting with BBCode style tags
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Godot's class reference supports BBCode-like tags. They add nice formatting to the text. Here's the list of available tags:
-
-+----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+
-| Tag                        | Effect                               | Usage                             | Result                                            |
-+============================+======================================+===================================+===================================================+
-| [Class]                    | Link a class                         | Move the [Sprite].                | Move the :ref:`class_sprite`.                     |
-+----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+
-| [method methodname]        | Link to a method in this class       | Call [method hide].               | See :ref:`hide <class_spatial_method_hide>`.      |
-+----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+
-| [method Class.methodname]  | Link to another class's method       | Call [method Spatial.hide].       | See :ref:`hide <class_spatial_method_hide>`.      |
-+----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+
-| [member membername]        | Link to a member in this class       | Get [member scale].               | Get :ref:`scale <class_node2d_property_scale>`.   |
-+----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+
-| [member Class.membername]  | Link to another class's member       | Get [member Node2D.scale].        | Get :ref:`scale <class_node2d_property_scale>`.   |
-+----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+
-| [signal signalname]        | Link to a signal in this class       | Emit [signal renamed].            | Emit :ref:`renamed <class_node_signal_renamed>`.  |
-+----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+
-| [signal Class.signalname]  | Link to another class's signal       | Emit [signal Node.renamed].       | Emit :ref:`renamed <class_node_signal_renamed>`.  |
-+----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+
-| [b] [/b]                   | Bold                                 | Some [b]bold[/b] text.            | Some **bold** text.                               |
-+----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+
-| [i] [/i]                   | Italic                               | Some [i]italic[/i] text.          | Some *italic* text.                               |
-+----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+
-| [code] [/code]             | Monospace                            | Some [code]monospace[/code] text. | Some ``monospace`` text.                          |
-+----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+
-| [kbd] [/kbd]               | Keyboard/mouse shortcut              | Some [kbd]Ctrl + C[/kbd] key.     | Some :kbd:`Ctrl + C` key.                         |
-+----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+
-| [codeblock] [/codeblock]   | Multiline preformatted block         | *See below.*                      | *See below.*                                      |
-+----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+
-| [codeblocks] [/codeblocks] | [codeblock] for multiple languages   | *See below.*                      | *See below.*                                      |
-+----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+
-| [gdscript] [/gdscript]     | GDScript codeblock tab in codeblocks | *See below.*                      | *See below.*                                      |
-+----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+
-| [csharp] [/csharp]         | C# codeblock tab in codeblocks       | *See below.*                      | *See below.*                                      |
-+----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+
-
-Use ``[codeblock]`` for pre-formatted code blocks. Inside ``[codeblock]``, always use **four spaces** for indentation (the parser will delete tabs). Example:
-
-.. code-block:: none
-
-    [codeblock]
-    func _ready():
-        var sprite = get_node("Sprite")
-        print(sprite.get_pos())
-    [/codeblock]
-
-Will display as:
-
-.. code-block:: gdscript
-
-    func _ready():
-        var sprite = get_node("Sprite")
-        print(sprite.get_pos())
-
-If you need to have different code version in GDScript and C#, use ``[codeblocks]`` instead. If you use ``[codeblocks]``, you also need to have at least one of the language specific tags (``[gdscript]`` and ``[csharp]``). Always write GDScript code examples first! You can use this `experimental code translation tool <https://github.com/HaSa1002/codetranslator>`_ to speed up your workflow.
-
-.. code-block:: none
-
-    [codeblocks]
-    [gdscript]
-    func _ready():
-        var sprite = get_node("Sprite")
-        print(sprite.get_pos())
-    [/gdscript]
-    [csharp]
-    public override void _Ready()
-    {
-        var sprite = GetNode("Sprite");
-        GD.Print(sprite.GetPos());
-    }
-    [/csharp]
-    [/codeblocks]
-
-Will display as:
-
-.. tabs::
- .. code-tab:: gdscript GDScript
-
-    func _ready():
-        var sprite = get_node("Sprite")
-        print(sprite.get_pos())
-
- .. code-tab:: csharp
-
-    public override void _Ready()
-    {
-        var sprite = GetNode("Sprite");
-        GD.Print(sprite.GetPos());
-    }
+To learn to create a pull request, read `Creating a pull request
+<https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request>`_
+in the GitHub documentation.
 
+.. warning::
 
-To denote important information, add a paragraph starting with "[b]Note:[/b]" at
-the end of the description:
-
-.. code-block:: none
-
-    [b]Note:[/b] Only available when using the Vulkan renderer.
-
-To denote crucial information that could cause security issues or loss of data
-if not followed carefully, add a paragraph starting with "[b]Warning:[/b]" at the
-end of the description:
-
-.. code-block:: none
-
-    [b]Warning:[/b] If this property is set to [code]true[/code], it allows clients to execute arbitrary code on the server.
-
-For deprecated properties, add a paragraph starting with "[i]Deprecated.[/i]".
-Notice the use of italics instead of bold:
-
-.. code-block:: none
+    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.
 
-    [i]Deprecated.[/i] This property has been replaced by [member other_property].
+    It lacks features to edit XML well, like keeping indentations consistent, and it does not allow amending commits based on reviews.
 
-In all the paragraphs described above, make sure the punctuation is part of the
-BBCode tags for consistency.
+    Also, it doesn't allow you to test your changes in the engine or with validation
+    scripts as described in
+    :ref:`doc_class_reference_writing_guidelines_editing_xml`.
 
-I don't know what this method does!
+Updating the documentation template
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-No problem. Leave it behind and list the methods you skipped when you request a pull of your changes. Another writer will take care of it.
+When you create a new class or modify the engine's API, you need to re-generate the XML files in ``doc/classes/``.
 
-You can still have a look at the methods' implementation in Godot's source code on GitHub. Also, if you have doubts, feel free to ask on the `Q&A website <https://godotengine.org/qa/>`__ and on IRC (freenode, #godotengine).
+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 executable with the ``--doctool`` option. If you're on 64-bit
+Linux, the command is:
 
+::
 
-Localization
-~~~~~~~~~~~~
-
-The documentation can be translated in any language on `Hosted Weblate
-<https://hosted.weblate.org/projects/godot-engine/godot-docs/>`__.
-
-Translated strings are synced manually by documentation maintainers in
-the `godot-docs-l10n <https://github.com/godotengine/godot-docs-l10n>`__
-repository.
+    ./bin/godot.linuxbsd.tools.64 --doctool .
 
-Languages with a good level of completion have their own localized
-instances of ReadTheDocs. Open an issue on the ``godot-docs-l10n``
-repository if you think that a new language is complete enough to get
-its own instance.
+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``.

community/contributing/ways_to_contribute.rst

@@ -176,20 +176,20 @@ Contributing to the documentation
 
 There are two separate resources referred to as "documentation" in Godot:
 
--  **The class reference.** This is the documentation for the complete Godot
-   API as exposed to GDScript and the other scripting languages. It can be
-   consulted offline, directly in Godot's code editor, or online at
-   :ref:`Godot API <toc-class-ref>`.
-   To contribute to the class reference, you have to edit the
+- **The class reference.** This is the documentation for the complete Godot API
+   as exposed to GDScript and the other scripting languages. It can be consulted
+   offline, directly in Godot's code editor, or online at :ref:`Godot API
+   <toc-class-ref>`. To contribute to the class reference, you have to edit the
    `doc/base/classes.xml` in Godot's Git repository, and make a pull request.
-   See :ref:`doc_updating_the_class_reference` for more details.
+   See :ref:`doc_updating_the_class_reference_with_git` and
+   :ref:`doc_class_reference_writing_guidelines` for more details.
 
 -  **The tutorials and engine documentation and its translations.** This is the part you are reading
    now, which is distributed in the HTML, PDF and EPUB formats. Its contents
    are generated from plain text files in the reStructured Text (rst) format,
    to which you can contribute via pull requests on the
    `godot-docs <https://github.com/godotengine/godot-docs>`_ GitHub repository.
-   See :ref:`doc_documentation_guidelines` for more details.
+   See :ref:`doc_contributing_to_the_documentation` for more details.
 
 Contributing translations
 -------------------------

development/cpp/custom_modules_in_cpp.rst

@@ -573,7 +573,7 @@ Now if you go to the ``godot/modules/summator/doc_classes`` folder, you will see
 that it contains a ``Summator.xml`` file, or any other classes, that you referenced
 in your ``get_doc_classes`` function.
 
-Edit the file(s) following :ref:`doc_updating_the_class_reference` and recompile the engine.
+Edit the file(s) following :ref:`doc_class_reference_writing_guidelines` and recompile the engine.
 
 Once the compilation process is finished, the docs will become accessible within
 the engine's built-in documentation system.

tutorials/ui/bbcode_in_richtextlabel.rst

@@ -15,8 +15,9 @@ a :ref:`class_RichTextLabel`.
 :ref:`class_RichTextLabel` allows the display of complex text markup in a Control.
 It has a built-in API for generating the markup, but can also parse a BBCode.
 
-Note that the BBCode tags can also be used, to some extent, in the
-:ref:`XML source of the class reference <doc_updating_the_class_reference>`.
+Note that the BBCode tags can also be used, to some extent, in the XML source of
+the class reference. For more information, see
+:ref:`doc_class_reference_writing_guidelines`.
 
 Using BBCode
 ------------