godotengine/godot-docs
1
0
Fork 0
mirror of https://github.com/godotengine/godot-docs.git synced 2026-01-05 22:09:56 +03:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
Update contribution guidelines
This commit is contained in:
Nathan Lovato
2020-11-23 14:58:53 -06:00
committed by GitHub
parent 436095b170 87a87205fb
commit 9cd09cc2d0
12 changed files with 773 additions and 563 deletions
Download Patch File Download Diff File Expand all files Collapse all files

134
README.md
View File

@@ -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".

2
about/introduction.rst
View File

@@ -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>`_.

99
community/contributing/building_the_manual.rst Normal file
View File

@@ -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.

254
community/contributing/class_reference_writing_guidelines.rst Normal file
View File

@@ -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).

190
community/contributing/contributing_to_the_documentation.rst Normal file
View File

@@ -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.

139
community/contributing/documentation_guidelines.rst
View File

@@ -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.

2
community/contributing/editor_and_docs_localization.rst
View File

@@ -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

92
community/contributing/index.rst
View File

@@ -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

403
community/contributing/updating_the_class_reference.rst
View File

@@ -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.
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.
**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>`__.
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.
.. seealso::
Not sure where to start contributing? Take a look at the current class reference
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`.
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 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>`_.
There are 5 steps to update the class reference (full guide below):
.. 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 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.
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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Alternatively, you can join the `Godot Discord server
<https://discord.gg/4JBkykG>`_ and participate in the ``#documentation``
channel.
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):
Submitting your changes
~~~~~~~~~~~~~~~~~~~~~~~
::
./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"
You are now ready to edit this file to add stuff.
**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).
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.
When it's done, you can ask for a pull request (abbreviated PR) on GitHub.
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::
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.
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.
TL;DR: If you don't know exactly what you're doing, do not edit files from GitHub.
It lacks features to edit XML well, like keeping indentations consistent, and it does not allow amending commits based on reviews.
How to edit class XML
---------------------
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`.
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 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!
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
~~~~~~~~~~~~
./bin/godot.linuxbsd.tools.64 --doctool .
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.
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``.

14
community/contributing/ways_to_contribute.rst
View File

@@ -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
-------------------------

2
development/cpp/custom_modules_in_cpp.rst
View File

@@ -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.

5
tutorials/ui/bbcode_in_richtextlabel.rst
View File

@@ -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
------------