stan220/godot-docs
1
0
Fork 0
mirror of https://github.com/stan220/godot-docs.git synced 2026-09-08 18:29:11 +00:00
Code Issues Packages Projects Releases Wiki Activity

Proof and rewrite the class ref contribution guide

Browse Source 
- edit to better fit the new writing guidelines: Shorten sentences, remove passive voice, etc
- shorten XML example
- add video guide
- detail git workflow
- add a 5 points bullet list to reflect the steps to contribute to the class reference
This commit is contained in:
Nathan Lovato
2017-09-11 09:45:52 +02:00
committed by Nathan
parent 30bc58bbda
commit 9cb30a854c
1 changed files with 114 additions and 250 deletions
Download Patch File Download Diff File Expand all files Collapse all files
community/contributing/updating_the_class_reference.rst
+114 -250
View File
@@ -1,160 +1,128 @@
.. _doc_updating_the_class_reference:
Updating the class reference
============================
Contribute to 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.
Godot ships with many nodes and singletons to help you develop your games in GDscript. 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 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!
But it's incomplete. Many 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, all of us, to contribute.
**Important notes:**
**Important:** we use `a collaborative document <https://hackmd.io/s/H1es51Oeqb>`_ to track who's working on what class. Always notify other writers about what you are working on. You'll find the instructions in the doc.
- To coordinate the effort and have an overview of the current status, we use
`a collaborative 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.
This guide is available as a `Youtube video <https://www.youtube.com/watch?v=mKKjOulm5XI>`_.
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.
How to contribute
-----------------
The workflow to update the class reference is therefore:
The class reference lies in the following XML file, in Godot's GitHub repository: `doc/base/classes.xml <https://github.com/godotengine/godot/blob/master/doc/base/classes.xml>`_. As it's over 1MB, you can't edit it online. To update the class reference:
- 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.
There are 5 steps to update the class reference (full guide below):
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.
1. Fork `Godot's repository <https://github.com/godotengine/godot>`_
2. Clone your fork on your computer
3. Edit the ``doc/base/classes.xml`` file to write documentation
4. Commit your changes and push them to your fork
5. Make a pull request on the Godot repository
**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.
**Important:** always use this XML file 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.
Getting started with GitHub
---------------------------
Get started with GitHub
-----------------------
This section describes step-by-step the typical workflow to fork the git repository,
or update an existing local clone of your fork, and then prepare a pull request.
If you're new to git and GitHub, this guide will help you get started. You'll learn to:
Fork Godot Engine
~~~~~~~~~~~~~~~~~
- 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
First of all, you need to fork the Godot Engine on your own GitHub
repository.
If you're brand new to git, the version-control system Godot uses, go through GitHub's interactive guide. You'll learn some essential vocabulary and get a sense for the tool.
https://try.github.io/levels/1/challenges/1
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.
Fork Godot
~~~~~~~~~~
Fork the Godot Engine into a GitHub repository of your own.
Clone the repository on your computer:
::
git clone https://github.com/your_name/godot.git
Then, create a new git branch that will contain your changes.
Create a new branch to make your changes. It makes it a lot easier to sync your improvements with other docs writers, and it's easier to cleanup your repository clean if you have any issues with git.
::
git checkout -b classref-edit
git checkout -b your-new-branch-name
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. Note that you can set whatever name
you want for the branch, ``classref-edit`` is just an example.
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.
Keeping your local clone up-to-date
How to keep your local clone up-to-date
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If you already have a local clone of your own fork, it might happen
pretty fast that it will diverge with the upstream git repository.
For example other contributors might have updated the class reference
since you last worked on it, or your own commits might have been squashed
together when merging your pull request, and thus appear as diverging
from the upstream master branch.
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.
To keep your local clone up-to-date, you should first add an ``upstream``
git *remote* to work with:
First add an ``upstream`` git *remote* to work with. Remotes are links to online repositories you can download new files from.
::
git remote add upstream https://github.com/godotengine/godot
git fetch upstream
You only need to run this once to define this remote. The following steps
will have to be run each time you want to sync your branch to the state
of the upstream repo:
You can check the list of all remote servers with:
::
git pull --rebase upstream/master
git remote -v
This command would reapply your local changes (if any) on top of the current
state of the upstream branch, thus bringing you up-to-date with your own commits
on top. In case you have local commits that should be discarded (e.g. if your
previous pull request had 5 small commits that were all merged into one bigger
commit in the upstream branch), you need to *reset* your branch:
You should have 2: ``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:
::
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.
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, i.e. it will discard all changes which are
specific to your local branch. So make sure to run this *before* making new
changes and not afterwards.
**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.
Alternatively, you can also keep your own master branch (``origin/master``)
up-to-date and create new branches when wanting to commit changes to the
class reference:
Another option is to delete the branch you're working on, synchronize the master branch with the Godot repository, and create a brand new branch:
::
git checkout master
git branch -d my-previous-doc-branch
git pull --rebase upstream/master
git checkout -b my-new-doc-branch
git branch -d your-new-branch-name
git pull --rebase upstream master
git checkout -b your-new-branch-name
In case of doubt, ask for help on our IRC channels, we have some git gurus
there.
If you're feeling lost by now, come to our `IRC channels <http://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):
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:
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:
::
@@ -163,9 +131,7 @@ starting to edit the template:
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).
**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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -179,23 +145,33 @@ 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 via the GitHub UI of your Godot fork.
Editing the doc/base/classes.xml file
-------------------------------------
How to edit classes.xml
-----------------------
This file is generated and updated by Godot Engine. It is used by the
editor as base for the Help section.
Edit the file doc/base/classes.xml to update the class reference. It lists all the classes, constants and methods in the class reference. Godot generates and updates it automatically.
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).
Edit it using your favourite text editor. If you use a code editor, make sure that it doesn't change the indent style. E.g. change all tabs to spaces.
Formatting of the XML file
~~~~~~~~~~~~~~~~~~~~~~~~~~
How to write the class reference
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Here is an example with the Node2D class:
Each class has a brief and a 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>
- <member></member>
- <signal></signal>
Write in a clear and simple language. Always follow the :ref:`class_reference_styleguide` 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.
For setters and getters, describe what the setter does in-depth, and only say the minimum in the getter to avoid content duplication. Setters and getters are methods that starts with set\_ or get\_.
Here's how a class looks like in XML:
.. code:: xml
@@ -214,88 +190,7 @@ Here is an example with the Node2D class:
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>
@@ -303,64 +198,34 @@ Here is an example with the Node2D class:
</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>
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
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, and fold the XML to navigate it faster.
<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!
Improve formatting with BBcode style tags
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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.
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 a method of this class | See [method set_pos]. | See :ref:`set_pos <class_node2d_set_pos>`. |
| [method methodname] | Link to a method in 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>`. |
| [method Class.methodname] | Link to another class's method | See [method Node2D.set_pos]. | See :ref:`set_pos <class_node2d_set_pos>`. |
+---------------------------+--------------------------------+-----------------------------------+--------------------------------------------+
| [b] [/b] | Bold | Some [b]bold[/b] text. | Some **bold** text. |
+---------------------------+--------------------------------+-----------------------------------+--------------------------------------------+
@@ -371,9 +236,7 @@ for more examples of how to use them properly.
| [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:
Use ``[codeblock]`` for pre-formatted code blocks, using spaces for indentation (the parser will delete tabs). Example:
.. code:: xml
@@ -383,7 +246,7 @@ reST converter). For example:
print(sprite.get_pos())
[/codeblock]
Which would be rendered as:
Will display as:
::
@@ -391,15 +254,16 @@ Which would be rendered as:
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.
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.
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
`Q&A website <https://godotengine.org/qa/>`__
and on IRC (freenode, #godotengine).
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).
Localization
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Before we translate the documentation, we need to complete and proof-read it in English. We'll work on localization when we get past 90% completion.