346 lines
14 KiB
ReStructuredText
346 lines
14 KiB
ReStructuredText
.. _doc_updating_the_class_reference:
|
|
|
|
Updating the class reference
|
|
============================
|
|
|
|
Godot Engine provides an extensive panel of nodes and singletons that you can
|
|
use with GDScript to develop your games. All those classes are listed and
|
|
documented in the :ref:`class reference <toc-class-ref>`, which is available
|
|
both in the online documentation and offline from within the engine.
|
|
|
|
The class reference is however not 100% complete. Some methods, constants and
|
|
signals have not been described yet, while others may have their implementation
|
|
changed and thus need an update. Updating the class reference is a tedious work
|
|
and the responsibility of the community: if we all partake in the effort, we
|
|
can fill in the blanks and ensure a good documentation level in no time!
|
|
|
|
**Important notes:**
|
|
|
|
- To coordinate the effort and have an overview of the current status, we use
|
|
this pad: **https://etherpad.net/p/godot-classref-status**. Please follow the
|
|
instructions there to notify the other documentation writers about what you
|
|
are working on.
|
|
- We aim at completely filling the class reference in English
|
|
first. Once it nears 90-95% completion, we could start thinking about
|
|
localisating in other languages.
|
|
|
|
Workflow for updating the class reference
|
|
-----------------------------------------
|
|
|
|
The source file of the class reference is an XML file in the main Godot source
|
|
repository on GitHub, `doc/base/classes.xml <https://github.com/godotengine/godot/blob/master/doc/base/classes.xml>`_.
|
|
As of now, it is relatively heavy (more than 1 MB), so it can't be edited online
|
|
using GitHub's text editor.
|
|
|
|
The workflow to update the class reference is therefore:
|
|
|
|
- Fork the `upstream repository <https://github.com/godotengine/godot>`_ and clone
|
|
your fork.
|
|
- Edit the ``doc/base/classes.xml`` file, commit your changes and push to your
|
|
fork.
|
|
- Make a pull request on the upstream repository.
|
|
|
|
The following section details this workflow, and gives also additional information
|
|
about how to synchronise the XML template with the current state of the source code,
|
|
or what should be the formatting of the added text.
|
|
|
|
**Important:** The class reference is also :ref:`available in the online documentation <toc-class-ref>`,
|
|
which is hosted alongside the rest of the documentation in the
|
|
`godot-docs <https://github.com/godotengine/godot-docs>`_ git repository. The rST files
|
|
should however **not be edited directly**, they are generated via a script from the
|
|
``doc/base/classes.xml`` file described above.
|
|
|
|
Getting started with GitHub
|
|
---------------------------
|
|
|
|
Fork Godot Engine
|
|
~~~~~~~~~~~~~~~~~
|
|
|
|
First of all, you need to fork the Godot Engine on your own GitHub
|
|
repository.
|
|
|
|
You will then need to clone the master branch of Godot Engine in order
|
|
to work on the most recent version of the engine, including all of its
|
|
features.
|
|
|
|
::
|
|
|
|
git clone https://github.com/your_name/godot.git
|
|
|
|
Then, create a new git branch that will contain your changes.
|
|
|
|
::
|
|
|
|
git checkout -b classref-edit
|
|
|
|
The branch you just created is identical to current master branch of
|
|
Godot Engine. It already contains a ``doc/`` folder, with the current
|
|
state of the class reference.
|
|
|
|
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.x11.tools.64 -doctool doc/base/classes.xml
|
|
|
|
The doc/base/classes.xml 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/base/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
|
|
repository:
|
|
|
|
::
|
|
|
|
git add doc/base/classes.xml
|
|
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.
|
|
|
|
Editing the doc/base/classes.xml file
|
|
-------------------------------------
|
|
|
|
This file is generated and updated by Godot Engine. It is used by the
|
|
editor as base for the Help section.
|
|
|
|
You can edit this file using your favourite text editor. If you use a code
|
|
editor, make sure that it won't needlessly change the indentation behaviour
|
|
(e.g. change all tabs to spaces).
|
|
|
|
Formatting of the XML file
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Here is an example with the Node2D class:
|
|
|
|
.. code:: xml
|
|
|
|
<class name="Node2D" inherits="CanvasItem" category="Core">
|
|
<brief_description>
|
|
Base node for 2D system.
|
|
</brief_description>
|
|
<description>
|
|
Base node for 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>
|
|
Set the position of the 2d node.
|
|
</description>
|
|
</method>
|
|
<method name="set_rot">
|
|
<argument index="0" name="rot" type="float">
|
|
</argument>
|
|
<description>
|
|
Set the rotation of the 2d node.
|
|
</description>
|
|
</method>
|
|
<method name="set_scale">
|
|
<argument index="0" name="scale" type="Vector2">
|
|
</argument>
|
|
<description>
|
|
Set the scale of the 2d node.
|
|
</description>
|
|
</method>
|
|
<method name="get_pos" qualifiers="const">
|
|
<return type="Vector2">
|
|
</return>
|
|
<description>
|
|
Return the position of the 2D node.
|
|
</description>
|
|
</method>
|
|
<method name="get_rot" qualifiers="const">
|
|
<return type="float">
|
|
</return>
|
|
<description>
|
|
Return the rotation of the 2D node.
|
|
</description>
|
|
</method>
|
|
<method name="get_scale" qualifiers="const">
|
|
<return type="Vector2">
|
|
</return>
|
|
<description>
|
|
Return the scale of the 2D node.
|
|
</description>
|
|
</method>
|
|
<method name="rotate">
|
|
<argument index="0" name="degrees" type="float">
|
|
</argument>
|
|
<description>
|
|
</description>
|
|
</method>
|
|
<method name="move_local_x">
|
|
<argument index="0" name="delta" type="float">
|
|
</argument>
|
|
<argument index="1" name="scaled" type="bool" default="false">
|
|
</argument>
|
|
<description>
|
|
</description>
|
|
</method>
|
|
<method name="move_local_y">
|
|
<argument index="0" name="delta" type="float">
|
|
</argument>
|
|
<argument index="1" name="scaled" type="bool" default="false">
|
|
</argument>
|
|
<description>
|
|
</description>
|
|
</method>
|
|
<method name="get_global_pos" qualifiers="const">
|
|
<return type="Vector2">
|
|
</return>
|
|
<description>
|
|
Return the global position of the 2D node.
|
|
</description>
|
|
</method>
|
|
<method name="set_global_pos">
|
|
<argument index="0" name="arg0" type="Vector2">
|
|
</argument>
|
|
<description>
|
|
</description>
|
|
</method>
|
|
<method name="set_transform">
|
|
<argument index="0" name="xform" type="Matrix32">
|
|
</argument>
|
|
<description>
|
|
</description>
|
|
</method>
|
|
<method name="set_global_transform">
|
|
<argument index="0" name="xform" type="Matrix32">
|
|
</argument>
|
|
<description>
|
|
</description>
|
|
</method>
|
|
<method name="edit_set_pivot">
|
|
<argument index="0" name="arg0" type="Vector2">
|
|
</argument>
|
|
<description>
|
|
</description>
|
|
</method>
|
|
</methods>
|
|
<constants>
|
|
</constants>
|
|
</class>
|
|
|
|
As you can see, some methods in this class have no description (i.e.
|
|
there is no text between their marks). This can also happen for the
|
|
``description`` and ``brief_description`` of the class, but in our example
|
|
they are already filled. Let's edit the description of the ``rotate()``
|
|
method:
|
|
|
|
.. code:: xml
|
|
|
|
<method name="rotate">
|
|
<argument index="0" name="degrees" type="float">
|
|
</argument>
|
|
<description>
|
|
Rotates the node of a given number of degrees.
|
|
</description>
|
|
</method>
|
|
|
|
That's all!
|
|
|
|
You simply have to write any missing text between these marks:
|
|
|
|
- <description></description>
|
|
- <brief_description></brief_description>
|
|
- <constant></constant>
|
|
- <member></member>
|
|
- <signal></signal>
|
|
|
|
Describe clearly and shortly what the method does, or what the
|
|
constant, member variable or signal mean. You can include an example
|
|
of use if needed. Try to use grammatically correct English, and check
|
|
the other descriptions to get an impression of the writing style.
|
|
|
|
For setters/getters, the convention is to describe in depth what the
|
|
method does in the setter, and to say only the minimal in the getter to
|
|
avoid duplication of the contents.
|
|
|
|
Tags available for improved formatting
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
For more control over the formatting of the help, Godot's XML
|
|
documentation supports various BBcode-like tags which are
|
|
interpreted by both the offline in-editor Help, as well as the
|
|
online documentation (via the reST converter).
|
|
|
|
Those tags are listed below. See existing documentation entries
|
|
for more examples of how to use them properly.
|
|
|
|
+---------------------------+--------------------------------+-----------------------------------+--------------------------------------------+
|
|
| Tag | Effect | Usage | Result |
|
|
+===========================+================================+===================================+============================================+
|
|
| [Class] | Link a class | Move the [Sprite]. | Move the :ref:`class_sprite`. |
|
|
+---------------------------+--------------------------------+-----------------------------------+--------------------------------------------+
|
|
| [method methodname] | Link a method of this class | See [method set_pos]. | See :ref:`set_pos <class_node2d_set_pos>`. |
|
|
+---------------------------+--------------------------------+-----------------------------------+--------------------------------------------+
|
|
| [method Class.methodname] | Link a method of another class | See [method Node2D.set_pos]. | See :ref:`set_pos <class_node2d_set_pos>`. |
|
|
+---------------------------+--------------------------------+-----------------------------------+--------------------------------------------+
|
|
| [b] [/b] | Bold | Some [b]bold[/b] text. | Some **bold** text. |
|
|
+---------------------------+--------------------------------+-----------------------------------+--------------------------------------------+
|
|
| [i] [/i] | Italic | Some [i]italic[/b] text. | Some *italic* text. |
|
|
+---------------------------+--------------------------------+-----------------------------------+--------------------------------------------+
|
|
| [code] [/code] | Monospace | Some [code]monospace[/code] text. | Some ``monospace`` text. |
|
|
+---------------------------+--------------------------------+-----------------------------------+--------------------------------------------+
|
|
| [codeblock] [/codeblock] | Multiline preformatted block | *See below.* | *See below.* |
|
|
+---------------------------+--------------------------------+-----------------------------------+--------------------------------------------+
|
|
|
|
The ``[codeblock]`` is meant to be used for pre-formatted code
|
|
block, using spaces as indentation (tabs will be removed by the
|
|
reST converter). For example:
|
|
|
|
.. code:: xml
|
|
|
|
[codeblock]
|
|
func _ready():
|
|
var sprite = get_node("Sprite")
|
|
print(sprite.get_pos())
|
|
[/codeblock]
|
|
|
|
Which would be rendered as:
|
|
|
|
::
|
|
|
|
func _ready():
|
|
var sprite = get_node("Sprite")
|
|
print(sprite.get_pos())
|
|
|
|
I don't know what this method does!
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Not a problem. Leave it behind for now, and don't forget to notify the
|
|
missing methods when you request a pull of your changes. Another
|
|
editor will take care of it.
|
|
|
|
If you wonder what a method does, you can still have a look at its
|
|
implementation in Godot Engine's source code on GitHub. Also, if you
|
|
have a doubt, feel free to ask on the
|
|
`Forums <http://www.godotengine.org/projects/godot-engine/boards>`__
|
|
and on IRC (freenode, #godotengine).
|