76 lines
3.3 KiB
ReStructuredText
76 lines
3.3 KiB
ReStructuredText
.. _doc_updating_the_class_reference:
|
|
|
|
Contributing to the class reference
|
|
===================================
|
|
|
|
.. highlight:: shell
|
|
|
|
The class reference is available online in the :ref:`classes <doc_class_reference>`
|
|
section of the documentation and in the Godot editor, from the help menu.
|
|
|
|
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::
|
|
|
|
You can find the writing guidelines for the class reference :ref:`here <doc_class_reference_writing_guidelines>`.
|
|
|
|
For details on Git usage and the pull request workflow, please
|
|
refer to the :ref:`doc_pr_workflow` page.
|
|
|
|
If you want to translate the class reference from English to another
|
|
language, see :ref:`doc_editor_and_docs_localization`.
|
|
|
|
This guide is also available as a `video tutorial on YouTube
|
|
<https://www.youtube.com/watch?v=5jeHXxeX-JY>`_.
|
|
|
|
.. 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/>`_.
|
|
|
|
You can find the source files for the class reference in Godot's GitHub
|
|
repository: `doc/classes/
|
|
<https://github.com/godotengine/godot/tree/master/doc/classes>`_.
|
|
|
|
.. note:: For some modules in the engine's source code, you'll find the XML
|
|
files in the ``modules/<module_name>/doc_classes/`` directory instead.
|
|
|
|
.. warning:: Always edit the API reference through these source XML files. Do
|
|
not edit the generated ``.rst`` files :ref:`in the online documentation
|
|
<doc_class_reference>`, hosted in the `godot-docs
|
|
<https://github.com/godotengine/godot-docs>`_ repository.
|
|
|
|
.. warning::
|
|
|
|
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.
|
|
|
|
It lacks features to edit XML well, like keeping indentations consistent, and it does not allow amending commits based on reviews.
|
|
|
|
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`.
|
|
|
|
Updating the documentation template
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
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 binary from the Godot root directory with the ``--doctool`` option.
|
|
For example, if you're on 64-bit Linux, the command is::
|
|
|
|
./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. 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``.
|