mirror of
https://github.com/godotengine/godot-contributing-docs.git
synced 2025-12-31 05:48:13 +03:00
Add documentation and class reference articles.
This commit is contained in:
Lukas Tenbrink
115
documentation/class_reference.rst
Normal file
115
documentation/class_reference.rst
Normal file
@@ -0,0 +1,115 @@
|
||||
.. _doc_updating_the_class_reference:
|
||||
|
||||
Contributing to the class reference
|
||||
===================================
|
||||
|
||||
.. highlight:: shell
|
||||
|
||||
The :ref:`Class reference <doc_class_reference>` is a set of articles describing
|
||||
the public API of the engine. This includes descriptions for various classes,
|
||||
methods, properties, and global objects, available for scripting. The class reference
|
||||
is available online, from the documentation sidebar, and in the Godot editor, from
|
||||
the help menu.
|
||||
|
||||
As the engine grows and features are added or modified, some parts of the class
|
||||
reference become obsolete and new descriptions and examples need to be added.
|
||||
While developers are required to document their work in the class reference when
|
||||
submitting a pull request, we can't expect every programmer to be a good
|
||||
technical writer. There is always work for contributors like you to polish
|
||||
existing and create missing reference material.
|
||||
|
||||
The source of the class reference
|
||||
---------------------------------
|
||||
|
||||
As the class reference is available in two places, online and in the editor, we need to
|
||||
take care to keep things in sync. To achieve this the `main Godot repository <https://github.com/godotengine/godot/>`_
|
||||
is picked as the source of truth, and the documentation for the class reference is tracked there.
|
||||
|
||||
.. warning::
|
||||
|
||||
You should **not** edit ``.rst`` files in the ``classes/`` folder of the
|
||||
`documentation repository <https://github.com/godotengine/godot-docs/>`_.
|
||||
These files are generated automatically and are synced manually by project
|
||||
maintainers. Read further to learn how to correctly edit the class reference.
|
||||
|
||||
In the main repository the class reference is stored in XML files, one for each exposed
|
||||
class or global object. The majority of these files is located in `doc/classes/
|
||||
<https://github.com/godotengine/godot/tree/master/doc/classes>`_, but some modules
|
||||
contain their own documentation as well. You will find it in the ``modules/<module_name>/doc_classes/``
|
||||
directory. To learn more about editing XML files refer to :ref:`doc_class_reference_primer`.
|
||||
|
||||
.. seealso::
|
||||
|
||||
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>`_.
|
||||
|
||||
**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.
|
||||
|
||||
What to contribute
|
||||
------------------
|
||||
|
||||
The natural place to start contributing is the classes that you are most familiar with.
|
||||
This ensures that the added description will be based on experience and the necessary
|
||||
know-how, not just the name of a method or a property. We advise not to add low effort
|
||||
descriptions, no matter how appealing it may look. Such descriptions obscure the need
|
||||
for documentation and are hard to identify automatically.
|
||||
|
||||
.. seealso::
|
||||
|
||||
Following this principle is important and allows us to create tools for contributors.
|
||||
Such as the class reference's `completion status tracker <https://godotengine.github.io/doc-status/>`_.
|
||||
You can use it to quickly find documentation pages missing descriptions.
|
||||
|
||||
If you decide to document a class, but don't know what a particular method does, don't
|
||||
worry. Leave it for now, and list the methods you skipped when you open a pull request
|
||||
with your changes. Another writer will take care of it.
|
||||
|
||||
You can still look at the method's implementation in Godot's source code on GitHub.
|
||||
If you have doubts, feel free to ask on the `Godot Forum <https://forum.godotengine.org/>`_
|
||||
and `Godot Contributors Chat <https://chat.godotengine.org/>`_.
|
||||
|
||||
.. 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 files. It lacks features to edit
|
||||
XML well, like keeping indentations consistent, and it does not allow amending commits
|
||||
based on reviews.
|
||||
|
||||
It also doesn't allow you to test your changes in the engine or with validation
|
||||
scripts as described in :ref:`doc_class_reference_editing_xml`.
|
||||
|
||||
|
||||
Updating class reference when working on the engine
|
||||
---------------------------------------------------
|
||||
|
||||
When you create a new class or modify an existing 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 might be:
|
||||
|
||||
::
|
||||
|
||||
./bin/godot.linuxbsd.editor.x86_64 --doctool
|
||||
|
||||
The exact set of suffixes may be different. Carefully read through the linked article to
|
||||
learn more about that.
|
||||
|
||||
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``, but consider reporting
|
||||
if you notice unrelated files being updated. Ideally, running this command should only
|
||||
bring up the changes that you yourself have made.
|
||||
|
||||
You will then need to add descriptions to any newly generated entries.
|
||||
215
documentation/documentation.rst
Normal file
215
documentation/documentation.rst
Normal file
@@ -0,0 +1,215 @@
|
||||
.. _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:`Class Reference <doc_class_reference>` 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`.
|
||||
|
||||
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. :ref:`doc_docs_writing_guidelines`. There, you will find rules and
|
||||
recommendations to write in a way that everyone understands.
|
||||
2. :ref:`doc_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. ``3.6`` or ``4.2``) if your changes only
|
||||
apply to that specific version of Godot. After a pull request is merged into
|
||||
``master``, it will usually be cherry-picked into the current stable branch by
|
||||
documentation maintainers.
|
||||
|
||||
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 :ref:`doc_updating_the_class_reference` 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, make sure the current branch is "master".
|
||||
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. Click "Commit changes...", summarize the changes you made
|
||||
and make sure to replace the placeholder "Update file.rst" by a short,
|
||||
but clear one-line description, as this is the commit title.
|
||||
Click the button **Propose changes**.
|
||||
|
||||
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*.
|
||||
|
||||
.. note::
|
||||
|
||||
If there are more commits than your own in the pull request
|
||||
it is likely that your branch was created using the wrong origin,
|
||||
due to "master" not being the current branch in step 2.
|
||||
You will need to rebase your branch to "master" or create a new branch.
|
||||
|
||||
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 proper 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 <https://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.webp
|
||||
|
||||
Alternatively, you can use the `figure` directive, which gives the image a contrasting
|
||||
border and allows centering it on the page.
|
||||
|
||||
.. code:: rst
|
||||
|
||||
.. figure:: img/image_name.webp
|
||||
:align: center
|
||||
|
||||
You can also include attachments 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:`file_name.zip <files/file_name.zip>`
|
||||
|
||||
Consider using the `godot-docs-project-starters <https://github.com/godotengine/godot-docs-project-starters>`
|
||||
repository for hosting support materials, such as project templates and asset packs.
|
||||
You can use a direct link to the generated archive from that repository with the regular
|
||||
link markup:
|
||||
|
||||
.. code:: rst
|
||||
|
||||
`file_name.zip <https://github.com/godotengine/godot-docs-project-starters/releases/download/latest-4.x/file_name.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://creativecommons.org/licenses/by/3.0/>`_, 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.
|
||||
@@ -1,5 +1,5 @@
|
||||
Getting started
|
||||
===============
|
||||
Overview
|
||||
========
|
||||
|
||||
There are two separate resources referred to as "documentation" in Godot:
|
||||
|
||||
Reference in New Issue
Block a user