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

Edit contributing guidelines

Browse Source 
Add links to the README
Simplify building the manual
Update class reference writing guidelines based on review notes. Re-add lost changes in rebase.
Address review comments in documentation guidelines
This commit is contained in:
Nathan Lovato
2020-11-13 08:49:59 -06:00
parent 1389aa4873
commit 1827f10937
7 changed files with 201 additions and 148 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
README.md
View File

@@ -25,8 +25,9 @@ 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/documentation_guidelines.html) 1. [Contributing to the online manual](https://docs.godotengine.org/en/latest/community/contributing/documentation_guidelines.html)
2. [Contributing to the class reference](https://docs.godotengine.org/en/latest/community/contributing/updating_the_class_reference.html) 2. [Contributing to the class reference](https://docs.godotengine.org/en/latest/community/contributing/updating_the_class_reference.html)
3. [Writing guidelines](https://docs.godotengine.org/en/latest/community/contributing/docs_writing_guidelines.html) 3. [Content guidelines](https://docs.godotengine.org/en/latest/community/contributing/content_guidelines.html)
4. [Translating the documentation](https://docs.godotengine.org/en/latest/community/contributing/editor_and_docs_localization.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 ## License

55
community/contributing/building_the_manual.rst
View File

@@ -7,20 +7,24 @@ 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 Sphinx docs engine. This allows you to have local HTML files and build the
documentation as a PDF, EPUB, or LaTeX file, for example. documentation as a PDF, EPUB, or LaTeX file, for example.
To get started, you need to install: To get started, you need to:
1. `Sphinx <https://www.sphinx-doc.org/>`__ 1. Clone the `godot-docs repository <https://github.com/godotengine/godot-docs/>`__.
2. To build the docs as HTML files, the `readthedocs.org theme 2. Install `Sphinx <https://www.sphinx-doc.org/>`__
<https://github.com/snide/sphinx_rtd_theme>`__ 3. To build the docs as HTML files, install the `readthedocs.org theme
3. The Sphinx extensions defined in this repository's ``requirements.txt`` file <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 We recommend using `pip <https://pip.pypa.io>` _, Python’s package manager to
install all these tools. It comes pre-installed with `Python install all these tools. It comes pre-installed with `Python
<https://www.python.org/>`__. Ensure that you install and use Python 3. <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 .. code:: sh
pip install -r requirements.txt 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 .. note:: On Linux distributions, you may need to write ``pip3`` instead of
``pip`` because you generally have both Python 2 and 3 installed on ``pip`` because you generally have both Python 2 and 3 installed on
@@ -32,13 +36,17 @@ folder of this repository with the following command:
.. code:: sh .. code:: sh
make html # 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: If you run into errors, you may try the following command:
.. code:: sh .. code:: sh
make SPHINXBUILD=~/.local/bin/sphinx-build html make SPHINXBUILD=~/.local/bin/sphinx-build html
Building the documentation requires at least 8 GB of RAM to run without disk 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 swapping, which slows it down. If you have at least 16 GB of RAM, you can speed
@@ -46,11 +54,11 @@ up compilation by running:
.. code:: sh .. code:: sh
# On Linux/macOS # On Linux/macOS
make html SPHINXOPTS=-j2 make html SPHINXOPTS=-j2
# On Windows # On Windows
set SPHINXOPTS=-j2 && make html set SPHINXOPTS=-j2 && make html
The compilation will take some time as the ``classes/`` folder contains hundreds The compilation will take some time as the ``classes/`` folder contains hundreds
of files. of files.
@@ -68,23 +76,6 @@ from the final HTML documentation but will keep the rest intact.
<https://github.com/godotengine/godot-docs/issues/3157>`__ for more <https://github.com/godotengine/godot-docs/issues/3157>`__ for more
detail. detail.
Building with Sphinx on Windows
-------------------------------
On Windows, you need to:
1. Download the Python installer `here <https://www.python.org/downloads/>`__.
2. Install Python. Be sure to check the “Add Python to PATH” checkbox.
3. Use the above ``pip`` commands to install required programs.
To build the documentation, open the root directory of this repository in your
command line and execute ``make.bat`` like so:
.. code:: sh
make.bat html
Alternatively, you can build the documentation by running the sphinx-build Alternatively, you can build the documentation by running the sphinx-build
program manually: program manually:
@@ -92,10 +83,6 @@ program manually:
sphinx-build -b html ./ _build 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. The build may hang until you confirm these prompts.
Building with Sphinx and virtualenv Building with Sphinx and virtualenv
----------------------------------- -----------------------------------

180
community/contributing/class_reference_writing_guidelines.rst
View File

@@ -16,34 +16,45 @@ The reference for each class is contained in an XML file like the one below:
.. code-block:: xml .. code-block:: xml
<class name="Node2D" inherits="CanvasItem" category="Core"> <class name="Node2D" inherits="CanvasItem" version="4.0">
<brief_description> <brief_description>
Base node for 2D system. A 2D game object, inherited by all 2D-related nodes. Has a position, rotation, scale, and Z index.
</brief_description> </brief_description>
<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. 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> </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> <methods>
<method name="set_pos"> <method name="apply_scale">
<argument index="0" name="pos" type="Vector2"> <return type="void">
</return>
<argument index="0" name="ratio" type="Vector2">
</argument> </argument>
<description> <description>
Sets the position of the 2D node. Multiplies the current scale by the [code]ratio[/code] vector.
</description> </description>
</method> </method>
[...] [...]
<method name="edit_set_pivot"> <method name="translate">
<argument index="0" name="arg0" type="Vector2"> <return type="void">
</return>
<argument index="0" name="offset" type="Vector2">
</argument> </argument>
<description> <description>
Translates the node by the given [code]offset[/code] in local coordinates.
</description> </description>
</method> </method>
</methods> </methods>
<members> <members>
<member name="global_position" type="Vector2" setter="set_global_position" getter="get_global_position" brief=""> <member name="global_position" type="Vector2" setter="set_global_position" getter="get_global_position">
Global position.
</member> </member>
[...] [...]
<member name="z_as_relative" type="bool" setter="set_z_as_relative" getter="is_z_relative" brief=""> <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> </member>
</members> </members>
<constants> <constants>
@@ -54,15 +65,16 @@ The reference for each class is contained in an XML file like the one below:
It starts with brief and long descriptions. In the generated docs, the brief 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 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, below the list of methods, variables, and constants. You can find methods,
member variables, constants, and signals in separate XML nodes. For each, learn member variables, constants, and signals in separate XML nodes.
how they work in Godot's source code, and fill their <description> tag.
Our job is to complete or improve the text in these tags: 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>` - `<brief_description>`
- `<description>` - `<description>`
- `<constant>` - `<constant>`
- `<method>` (in its `<description>` tag; return types and arguments don't take separate documentation strings) - `<method>` (in its `<description>` tag; return types and arguments don't take separate
documentation strings)
- `<member>` - `<member>`
- `<signal>` (in its `<description>` tag; arguments don't take separate documentation strings) - `<signal>` (in its `<description>` tag; arguments don't take separate documentation strings)
- `<constant>` - `<constant>`
@@ -72,6 +84,8 @@ Write in a clear and simple language. Always follow the :ref:`writing guidelines
**Do not leave empty lines** in the descriptions: each line in the XML file will **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. result in a new paragraph, even if it is empty.
.. _doc_class_reference_writing_guidelines_editing_xml:
How to edit class XML How to edit class XML
--------------------- ---------------------
@@ -80,20 +94,27 @@ 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 constants and methods you will find in the class reference. Godot generates and
updates the XML automatically. 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 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 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. four spaces inside BBCode-style blocks. More on that below.
To check that the modifications you've made are correct in the To check that the modifications you've made are correct in the generated
generated documentation, you need to build Godot. To learn how, read the documentation, navigate to the ``doc/`` folder and run the command ``make rst``.
:ref:`compilation guide <toc-devel-compiling>`. Then, run the editor and open This will convert the XML files to the online documentation's format and output
the help for the page you modified. 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, 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 Notepad++, or another to comfortably edit the file. You can also use their
search feature to find classes and properties quickly. search feature to find classes and properties quickly.
.. _doc_updating_the_class_reference_bbcode: .. _doc_class_reference_writing_guidelines_bbcode:
Improve formatting with BBCode style tags Improve formatting with BBCode style tags
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -101,33 +122,39 @@ Improve formatting with BBCode style tags
Godot's class reference supports BBCode-like tags. They add nice formatting to Godot's class reference supports BBCode-like tags. They add nice formatting to
the text. Here's the list of available tags: the text. Here's the list of available tags:
+---------------------------+--------------------------------+-----------------------------------+---------------------------------------------------+ +----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+
| Tag | Effect | Usage | Result | | Tag | Effect | Usage | Result |
+===========================+================================+===================================+===================================================+ +============================+======================================+===================================+===================================================+
| [Class] | Link a class | Move the [Sprite]. | Move the :ref:`class_sprite`. | | [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 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>`. | | [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 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>`. | | [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 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>`. | | [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. | | [b] [/b] | Bold | Some [b]bold[/b] text. | Some **bold** text. |
+---------------------------+--------------------------------+-----------------------------------+---------------------------------------------------+ +----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+
| [i] [/i] | Italic | Some [i]italic[/i] text. | Some *italic* text. | | [i] [/i] | Italic | Some [i]italic[/i] text. | Some *italic* text. |
+---------------------------+--------------------------------+-----------------------------------+---------------------------------------------------+ +----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+
| [code] [/code] | Monospace | Some [code]monospace[/code] text. | Some ``monospace`` 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. | | [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.* | | [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]``, Use ``[codeblock]`` for pre-formatted code blocks. Inside ``[codeblock]``,
always use **four spaces** for indentation. The parser will delete tabs. For always use **four spaces** for indentation. The parser will delete tabs. For
@@ -135,14 +162,61 @@ example:
.. code-block:: none .. code-block:: none
[codeblock] func _ready(): var sprite = get_node("Sprite") [codeblock]
print(sprite.get_pos()) [/codeblock] func _ready():
var sprite = get_node("Sprite")
print(sprite.get_pos())
[/codeblock]
Will display as: Will display as:
.. code-block:: gdscript .. code-block:: gdscript
func _ready(): var sprite = get_node("Sprite") print(sprite.get_pos()) 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 To denote important information, add a paragraph starting with "[b]Note:[/b]" at
the end of the description: the end of the description:
@@ -157,16 +231,14 @@ the end of the description:
.. code-block:: none .. code-block:: none
[b]Warning:[/b] If this property is set to [code]true[/code], it allows [b]Warning:[/b] If this property is set to [code]true[/code], it allows clients to execute arbitrary code on the server.
clients to execute arbitrary code on the server.
For deprecated properties, add a paragraph starting with "[i]Deprecated.[/i]". For deprecated properties, add a paragraph starting with "[i]Deprecated.[/i]".
Notice the use of italics instead of bold: Notice the use of italics instead of bold:
.. code-block:: none .. code-block:: none
[i]Deprecated.[/i] This property has been replaced by [member [i]Deprecated.[/i] This property has been replaced by [member other_property].
other_property].
In all the paragraphs described above, make sure the punctuation is part of the In all the paragraphs described above, make sure the punctuation is part of the
BBCode tags for consistency. BBCode tags for consistency.

34
community/contributing/documentation_guidelines.rst
View File

@@ -49,7 +49,7 @@ contribute, you should also read:
Contributing changes Contributing changes
-------------------- --------------------
**Pull Requests should use the ``master`` branch by default**. Only make Pull **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 Requests against other branches (e.g. ``2.1`` or ``3.0``) if your changes only
apply to that specific version of Godot. apply to that specific version of Godot.
@@ -69,6 +69,9 @@ See `Contribute to the Class Reference
<https://docs.godotengine.org/en/latest/community/contributing/updating_the_class_reference.html>`__ <https://docs.godotengine.org/en/latest/community/contributing/updating_the_class_reference.html>`__
for details. for details.
.. seealso:: To build the manual and test changes on your computer, see
:ref:`doc_building_the_manual`
Editing pages online Editing pages online
-------------------- --------------------
@@ -100,19 +103,20 @@ they're good. They may also make changes or ask you to do so before merging.
Adding new pages 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 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 want to add a file to, e.g. ``tutorials/3d/light_baking.rst``.
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, 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 e.g. ``tutorials/3d/index.rst``). Add your new filename to the list on a new
various levels of toctree are prefixed with an underscore, so in the above line, using a relative path and no extension, e.g. here ``light_baking``.
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``.
Titles Titles
~~~~~~ ~~~~~~
@@ -126,6 +130,8 @@ Always begin pages with their title and a Sphinx reference name:
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. 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 ``:ref:`doc_insert_your_title_here``` would link to the above example page (note
the lack of leading underscore in the reference). the lack of leading underscore in the reference).
@@ -148,8 +154,10 @@ details on the syntax.
Sphinx uses specific reST comments to do specific operations, like defining the Sphinx uses specific reST comments to do specific operations, like defining the
table of contents (``.. toctree::``) or cross-referencing pages. Check the table of contents (``.. toctree::``) or cross-referencing pages. Check the
`official Sphinx documentation `official Sphinx documentation
<https://www.sphinx-doc.org/en/stable/index.html>`__ for more details, or see <https://www.sphinx-doc.org/en/stable/index.html>`__ for more details. To learn
how things are done in existing pages and adapt it to your needs. 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 Adding images and attachments
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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:: .. seealso::
See our documentation for class reference writers for the :ref:`list of 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. throughout the class reference.
Offline translation and testing Offline translation and testing

1
community/contributing/index.rst
View File

@@ -38,6 +38,7 @@ Writing documentation
:name: toc-community-contributing-to-documentation :name: toc-community-contributing-to-documentation
documentation_guidelines documentation_guidelines
content_guidelines
docs_writing_guidelines docs_writing_guidelines
updating_the_class_reference updating_the_class_reference
class_reference_writing_guidelines class_reference_writing_guidelines

72
community/contributing/updating_the_class_reference.rst
View File

@@ -41,6 +41,9 @@ You can find the source files for the class reference in Godot's GitHub
repository: `doc/classes/ repository: `doc/classes/
<https://github.com/godotengine/godot/tree/master/doc/classes>`_. <https://github.com/godotengine/godot/tree/master/doc/classes>`_.
.. note:: For some modules in the engine's source code, you'll find the XML
files in the ``modules/<module_name>/doc_classes/`` directory instead.
There are five steps to update the class reference: There are five steps to update the class reference:
1. Fork `Godot's repository <https://github.com/godotengine/godot>`_ 1. Fork `Godot's repository <https://github.com/godotengine/godot>`_
@@ -103,7 +106,7 @@ Keeping your local clone up-to-date
Other writers contribute to Godot's documentation. Your local repository will Other writers contribute to Godot's documentation. Your local repository will
fall behind it. You will have to synchronize it, especially if other fall behind it. You will have to synchronize it, especially if other
contributors update the class reference while working on it. contributors update the class reference while you are working on it.
First, add an ``upstream`` Git *remote*. Remotes are links to online repositories 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 from which you can download new files. The following command registers a new
@@ -113,27 +116,6 @@ remote named "upstream" that links to the original Godot repository.
git remote add upstream https://github.com/godotengine/godot git remote add upstream https://github.com/godotengine/godot
You can check the list of all remote servers with this command:
::
git remote -v
You should have two remotes:
1. ``origin``, corresponding to your fork on GitHub. Git adds it by default when
you clone a repository.
2. ``upstream``, that you just added.
The output should look like the following:
::
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 synchronize your branch with the upstream repository, Each time you want to synchronize your branch with the upstream repository,
enter: enter:
@@ -161,13 +143,19 @@ branch with the Godot repository, and create a new branch:
:: ::
git checkout master git branch -d your-new-branch-name git pull --rebase git checkout master
upstream master git checkout -b 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 If you're feeling lost by now, come to our `IRC channels
<https://webchat.freenode.net/?channels=#godotengine>`_ and ask for help. <https://webchat.freenode.net/?channels=#godotengine>`_ and ask for help.
Experienced Git users will give you a hand. Experienced Git users will give you a hand.
Alternatively, you can join the `Godot Discord server
<https://discord.gg/4JBkykG>`_ and participate in the ``#documentation``
channel.
Submitting your changes Submitting your changes
~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~
@@ -188,33 +176,29 @@ in the GitHub documentation.
.. warning:: .. warning::
You should avoid editing files directly on GitHub in the godot engine 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.
repository. As hundreds of contributors work on the engine, the Git history
must stay clean. Each commit should bundle all related improvements you make
to the class reference.
Editing from GitHub creates a new branch and Pull Request every time you It lacks features to edit XML well, like keeping indentations consistent, and it does not allow amending commits based on reviews.
save your changes. Suppose days pass before your changes get a review. In
that case, you won't be able to update to the latest version of the Also, it doesn't allow you to test your changes in the engine or with validation
repository cleanly. Also, it's harder to keep clean indents with GitHub's scripts as described in
text editor. And they're essential in the class reference. :ref:`doc_class_reference_writing_guidelines_editing_xml`.
Updating the documentation template 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 you create a new class or modify the engine's API, you need to re-generate the XML files in ``doc/classes/``.
To do so, you first need to compile Godot. See the
:ref:`doc_introduction_to_the_buildsystem` page to learn how. Then, execute the
compiled godot executable with the ``--doctool`` option. If you're on 64-bit
Linux, the command is:
:: ::
./bin/godot.linuxbsd.tools.64 --doctool . ./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: 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``.
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).