godotengine/godot-contributing-docs
1
0
Fork 0
mirror of https://github.com/godotengine/godot-contributing-docs.git synced 2026-01-03 18:09:19 +03:00
Code Issues Packages Projects Releases Wiki Activity

Use more of the 'contributing' part of godot docs to fill in for documentation contribution guides.

Browse Source
This commit is contained in:
Lukas Tenbrink
2025-07-30 01:37:45 +02:00
parent e5358ebad8
commit 8f8011a14b
14 changed files with 1968 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files

94
documentation/guidelines/content_guidelines.rst Normal file
View File

@@ -0,0 +1,94 @@
.. _doc_content_guidelines:
Content guidelines
==================
This document outlines what should be included in the official documentation.
Below, you will find a couple of principles and recommendations for writing
accessible content.
We want to achieve two goals:
1. **Empathize with our users.** We should write in a way that makes it easy for
them to learn from the docs.
2. **Write a complete reference manual**. Our goal here is not to teach
programming fundamentals. Instead, our goal is to provide a reference for how
Godot's features work.
Guidelines and principles
-------------------------
Below are the guidelines we should strive to follow. They are not hard rules,
though: sometimes, a topic will require breaking one or more of them.
Still, we should strive to achieve the two goals listed above.
Writing complete and accessible documentation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
**A feature doesn't exist unless it is documented**. If a user can't find
information about a feature and how it works, it doesn't exist to them. We
should ensure that we cover everything Godot does.
.. note::
When adding or updating an engine feature, the documentation team needs to
know about it. Contributors should open an issue on the `godot-docs` repository
when their work gets merged and requires documentation.
Do your best to keep documents **under 1000 words in length**. If a page goes
past that threshold, consider splitting it into two parts. Limiting page size
forces us to write concisely and to break up large documents so that each page
focuses on a particular problem.
Each page or section of a page should clearly state what **problem** it tackles
and what it will teach the user. Users need to know if they're reading the
correct guide for solving the problems they're encountering. For example,
instead of writing the heading "Signals", consider writing "Reacting to changes
with signals". The second title makes it clear what the purpose of signals is.
.. note::
Long section titles lead to long entries in the side menu, which can make
navigation cumbersome. Try to keep headings five words long or less.
If the page assumes specific knowledge of other Godot features, mention it and
link to the corresponding documentation. For instance, a page about physics
may use signals, in which case you could note that the signals tutorial is a
prerequisite. You may also link to other websites for prerequisites beyond the
documentation's scope. For example, you could link to an introduction to
programming in the getting started guide, or a website that teaches math theory
in the math section.
Limiting cognitive load
~~~~~~~~~~~~~~~~~~~~~~~
Limit the cognitive load required to read the documentation. The simpler and
more explicit language we use, the more efficient it becomes for people to
learn. You can do so by:
1. Introducing only one new concept at a time whenever possible.
2. Using simple English, as we recommend in our writing guidelines.
3. Including one or more **concrete usage examples**. Prefer a real-world example
to one that uses names like ``foo``, ``bar``, or ``baz``.
While many people may understand more complex language and abstract examples,
you will lose others. Understandable writing and practical examples benefit
everyone.
Always make an effort to **put yourself in the user's shoes**. When we
understand something thoroughly, it becomes obvious to us. We may fail to think
about details relevant to a newcomer, but **good documentation meets users where
they are**. We should explain each feature's capabilities or intended uses with
the most straightforward language possible.
Try to remember what you first needed to know when learning about the feature or
concept. What new terms did you need to learn? What confused you? What was the
hardest to grasp? You will want users to review your work, and we recommend you
practice explaining the feature before writing about it.
.. note::
Programming fundamentals are a prerequisite for using a complex engine like
Godot. Talking about variables, functions, or classes is acceptable. But we
should favor plain language over specific terminology like
"metaprogramming". If you need to use precise terms, be sure to define them.

71
documentation/guidelines/docs_contribution_checklist.rst Normal file
View File

@@ -0,0 +1,71 @@
.. _docs_contribution_checklist:
Documentation contribution checklist
====================================
This page is a summary of the guidelines to follow when contributing to the
documentation. Before you press that **Create pull request** button on GitHub,
read over this list to double check if you missed anything.
You don't need to read all the guidelines here in order to start contributing.
If you do miss something, it will be pointed out during review. However,
following the guidelines you are aware of as best you can will help speed up the
review process.
Writing style
-------------
:ref:`See here. <doc_docs_writing_guidelines_clear_english_rules>`
- Use the active voice.
- Use precise action verbs.
- Avoid verbs that end in -ing.
- Remove unnecessary adverbs and adjectives.
- Ban these 8 words: obvious, simple, basic, easy, actual, just, clear, and however.
- Use explicit references.
- Use 's to show possession.
- Use the Oxford comma.
Code examples
-------------
- Use dynamic typing. :ref:`See here. <doc_docs_writing_guidelines_dynamic_typing>`
- Use real, practical examples. Avoid ``foo`` / ``bar`` examples. :ref:`See here. <doc_docs_writing_guidelines_real_world_code_example>`
Manual style and formatting
---------------------------
- Use common vocabulary for the editor interface. :ref:`See here. <doc_docs_writing_guidelines_common_vocabulary>`
- Use ``:kbd:`` for keyboard shortcuts. :ref:`See here. <doc_docs_writing_guidelines_keyboard_shortcuts>`
- Literals use ``code style``. :ref:`See here. <doc_docs_writing_guidelines_literals>`
- Classes link to the class reference once, then use ``ClassName`` for the rest
of the page.
Methods and properties link to the class ref once, then use ``PropertyName``
for the rest of the page. :ref:`See here. <doc_docs_writing_guidelines_class_properties_methods>`
- Editor UI, like menus, windows, and editor navigation paths, use
``Bold Style``. :ref:`See here. <doc_docs_writing_guidelines_editor_ui>`
- Link to project settings when referencing them. :ref:`See here. <doc_docs_writing_guidelines_project_settings>`
- Text is manually wrapped to 80-100 characters. :ref:`See here. <doc_docs_writing_guidelines_manually_wrapping_lines>`
- No trailing whitespace at the end of lines.
- Most of the time, avoid mentioning a specific Godot version. :ref:`See here. <doc_docs_writing_guidelines_specific_version>`
Images and videos
-----------------
- New (and updated) images are in WebP format. :ref:`See here. <doc_docs_image_guidelines_format_conversion>`
- Editor screenshots are cropped. :ref:`See here. <doc_docs_image_guidelines_cropping>`
- Images larger than 1080p or 300kb are scaled down. :ref:`See here. <doc_docs_image_guidelines_scaling_down>`
- Outlines in images use ``fffb44`` yellow. :ref:`See here. <doc_docs_image_guidelines_outlines>`
- Videos use the ``:autoplay:``, ``:loop:``, and ``:muted:`` tags. :ref:`See here. <doc_docs_image_guidelines_videos>`
GitHub
------
- The PR title starts with a word like ``Fix``, ``Add``, ``Update``,
``Clarify``, or ``Improve``.
- If the PR closes an issue, link to the issue with one of GitHub's
`keywords <https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/using-keywords-in-issues-and-pull-requests>`__:
``closes``, ``fixes``, or ``resolves``, in the text of the PR.
- Ideally, PR contains a single commit. However, multiple commits can be
:ref:`squashed <doc_pr_workflow_rebase>` later.

267
documentation/guidelines/docs_image_guidelines.rst Normal file
View File

@@ -0,0 +1,267 @@
.. _docs_image_guidelines:
Creating documentation images and videos
========================================
Throughout the documentation, images are often needed to make the explanation
of a feature or concept as clear as possible for a reader. This page will
explain the process from beginning to end.
Images
------
Capturing an image
~~~~~~~~~~~~~~~~~~
To take a picture of something in Godot, a screen capture tool can be used.
On Windows 10 and 11 that would be the Snip & Sketch program.
Pressing :kbd:`Windows + Shift + S` lets you take a screenshot
of a portion of the screen and save it to the clipboard.
After pressing those keys, click and drag over
the area you wish to take a picture of.
On macOS, pressing :kbd:`Shift + Command + 3` does the same.
To take a picture of the entire screen press :kbd:`Shift + Command + 4`.
All screenshots taken will be saved to the desktop.
Each Linux desktop environment has its own screenshot tool. For example,
on KDE Plasma the program Spectacle is used for taking screenshots. If your
distribution doesn't come with one by default try searching its package
repository, or Flathub if that's supported.
All screenshots should ideally be taken on a 1080p screen. Anything higher
resolution is adding detail that doesn't make the documentation better and
dramatically increases file size. If you're taking screenshots on a higher
resolution screen the screenshot should be scaled down. There are instructions
on how to do this later on this page.
.. _doc_docs_image_guidelines_format_conversion:
Format conversion
~~~~~~~~~~~~~~~~~
The current format for images in Godot's documentation is WebP (``.webp``).
While some Linux programs will support saving screenshots in this format, macOS
and the Snip & Sketch program on Windows do not. For images that don't need
editing, such as precise cropping or adding outlines, Squoosh can be used.
`Squoosh <https://squoosh.app/>`_ is a converter developed by Google, is open
source, and doesn't give Google any image rights by using it. When choosing
compression if you can get an image that's under 300KB in size use lossless
compression. If it's over 300KB, use just enough lossy compression to get it
under that size. If this results in noticeable compression artifacts using less
compression is fine, even if the file size is bigger.
If you already have an image editor such as GIMP, Krita or Photoshop installed
it may have the ability to open an image then save it as a WebP file.
.. note::
Since WebP supports animations and the documentation can display videos,
GIFs should be avoided. Their compression is inefficient and they only support
a 256-color palette with 1-bit transparency.
.. _doc_docs_image_guidelines_cropping:
Cropping
~~~~~~~~
For a screenshot of a 2D or 3D scene in the editor, the above steps will be enough.
But for most UI images some extra work should be done, specifically cropping to
make an image look clean. Below is an example of good cropping.
.. image:: img/cropped_image.webp
For cropping Krita is the recommended program. While some screenshot programs do
have cropping built-in it's not always easy to get something precise. And while
Krita is designed as a painting program the cropping tool gives you pixel precision
by default. Of course, feel free to use a different program you are familiar with.
If you've never used Krita before download it from the `official Krita website <https://krita.org/en/download/>`_,
on Linux you may also be able to download it from your distributions repository,
flathub is also an option. Once it's installed on your computer open Krita then
open the image you want to crop. This button on the left panel is the crop tool.
.. image:: img/crop_tool.webp
After selecting it, click on the image, you should now have cropping tools available.
.. image:: img/crop_edit.webp
Click and drag the white boxes to adjust what gets cropped, if you zoom in close
to the image you will see the individual pixels in an image, which is useful for
precision.
.. image:: img/crop_pixels.webp
If you make a mistake and overcrop don't worry, cropping is non-destructive in
Krita and can be adjusted. Click on the image with your cropping tool still selected
and the controls will return.
.. _doc_docs_image_guidelines_scaling_down:
Scaling down an image
~~~~~~~~~~~~~~~~~~~~~
As explained earlier on this page, all images taken on a screen that is a higher resolution
than 1080p should be scaled down. To do this in Krita click on **Image** on the top bar, and
from the dropdown menu select **Scale Image To New Size**. This menu can also be opened by
pressing :kbd:`Ctrl + Alt + I`. On this menu you want to adjust the pixel dimensions. For
anything taken on a 4K monitor change the value of the width and height to half of its current
value, for anything taken on a 1440p monitor multiply the width and height by 0.75. Make
sure the **Constrain Proportions** box at the bottom of the menu is checked so you only have
to change 1 value.
Saving as WebP in Krita
~~~~~~~~~~~~~~~~~~~~~~~
To save an image as webp if it isn't already one, Go to **File > Save As**. Select **webp** from the
**Save as type:** dropdown, then choose wherever you want to save it. After clicking **Save** a menu
will popup with webp options. Make sure **Lossless** is checked and **Quality** is set to 100%. This
means the image will not lose detail and will be as small as possible.
If the image is over 300KB in size try compressing it losslessly using `Squoosh <https://squoosh.app/>`_.
If it's still over 300KB change to lossy compression and slowly increase the compression until it's under
300KB. If this results in noticeable compression artifacts using less compression is fine, even if the file
size is bigger.
.. _doc_docs_image_guidelines_outlines:
Outlines, arrows and text
~~~~~~~~~~~~~~~~~~~~~~~~~
Sometimes an image needs something extra to properly direct the readers
attention, or make something clear. Outlines and arrows can be used
for this purpose. For these types of edits Inkscape is the recommended open
source program, it can be downloaded from the `official Inkscape website <https://inkscape.org/>`_.
Like Krita, if you're on Linux you can also check your distributions repository
or get it from Flathub.
A full tutorial on creating outlines is not provided here, we recommend searching
for various tutorials on how to use it online. However there are two standards
for doc image outlines and arrows. First, the color should be yellow, specifically
this hex color: ``fffb44`` (``fffb44ff`` if there is a transparency value like in Inkscape).
This color was chosen specifically to make sure color blind people do not have
issues reading the documentation, other colors can be used in addition to this yellow
if multiple outlines on an image are needed, red should be avoided. The second standard
is that all outlines and arrow lines should be 2 pixels wide.
Finally, some images might require text to differentiate multiple parts of an image.
There are no strict requirements other than use an easy to read non fancy font. As for
color the yellow color from before should also be used, but black or other colors can
be used if appropriate. For example, if yellow blends into the image, or if there are
multiple outlines in multiple colors.
Adding an image to a documentation page
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Once you've finished working on your image, it can be added to the documentation.
All images are stored in folders named ``img`` next to the page they are used in.
To add your image, add it to the ``img`` folder that's in the same folder as the
``.rst`` file for the page (create it if it doesn't exist). In the ``.rst`` page,
images should be included with the following code snippet:
::
.. image:: img/documentation_image.webp
Where ``documentation_image.webp`` would be changed to the name of the image you
created. Name your images in a way that makes their meaning clear, possibly with
a prefix that makes their relationship to a documentation page explicit.
.. _doc_docs_image_guidelines_videos:
Videos
------
Capturing a video
~~~~~~~~~~~~~~~~~
To record a video of something in Godot, a screen capture tool can be used.
Operating systems generally don't come with tools that are flexible enough
for this, so you'll need to install a third-party utility.
`OBS Studio <https://obsproject.com/>`__ is the most popular option, but
`SimpleScreenRecorder <https://www.maartenbaert.be/simplescreenrecorder/>`__
can be used as an alternative on Linux. `ShareX <https://getsharex.com/>`__
can be used as an alternative on Windows. All these tools can be configured
to record the entire screen, a specific window or a predetermined rectangle.
The recommended framerate for video recordings is 60 FPS, although you can use
30 FPS for longer videos to reduce their file size. For fullscreen videos,
use a resolution of 1280×720.
.. note::
Godot's :ref:`Movie Maker mode <doc_creating_movies>` can be used to record
the output of a running project, including its audio. This doesn't require
installing any third-party software and avoids any frame drops (even when
recording on a slow device), but it's less flexible.
Compressing the captured video
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The recommendation is to record your video in the highest quality possible
(without dropping frames due to excessive CPU/GPU utilization), then re-encode
it later to reduce its file size. This results in more efficient compression
than directly aiming for a small file size, as real-time compression methods are
less efficient than slower compression methods.
To re-encode videos for a smaller file size, use `HandBrake <https://handbrake.fr/>`__
or the `FFmpeg <https://ffmpeg.org/>` command line below:
::
ffmpeg -i input.mp4 -crf 23 output.webm
The number after ``-crf`` adjusts the video quality, with higher numbers
resulting in *lower* quality (and smaller file sizes). A CRF of ``23`` is a good
starting point, but you may need to use a higher value for longer videos to
ensure the file size remains reasonable. Try to aim for a file size under 2 MB
if possible.
If the video was recorded in a higher resolution or framerate, you can adjust
its output resolution and framerate as follows:
::
ffmpeg -i input.mp4 -crf 23 -vf scale=1280:-2 -r 30 output.webm
This results in a video resolution around 1280×720 at 30 FPS. The exact
video resolution will vary depending on the source's aspect ratio.
.. tip::
If the video was recorded with an audio track but this audio track is not
necessary, consider stripping it by adding the ``-an`` option to the FFmpeg
command line (before the output file name). This will reduce file size and
also ensure audio controls don't show up on the video when played in a
browser.
Adding a video to a documentation page
--------------------------------------
Once you've finished working on your video, it can be added to the documentation.
All videos are stored in folders named ``video`` next to the page they are used in.
To add your video, add it to the ``video`` folder that's in the same folder as the
``.rst`` file for the page (create it if it doesn't exist). In the ``.rst`` page,
videos should be included with the following code snippet:
::
.. video:: video/csg_tools.webm
:alt: Put a text description of the video here
:autoplay:
:loop:
:muted:
:align: default
Where ``documentation_video.webp`` would be changed to the name of the video you
created. Name your videos in a way that makes their meaning clear, possibly with
a prefix that makes their relationship to a documentation page explicit.
The ``:autoplay:``, ``:loop:`` and ``:muted:`` flags should always be specified
unless the video needs to play audio. In this case, do not specify *any* of these flags.
The ``:align: default`` flag should always be specified.

917
documentation/guidelines/docs_writing_guidelines.rst Normal file
View File

@@ -0,0 +1,917 @@
.. _doc_docs_writing_guidelines:
Writing guidelines
==================
The Godot community is rich and international. Users come from all
around the world. Some of them are young, and many aren't native English
speakers. That's why we must all write using a clear and a common
language. For the class reference, the goal is to make it easy to read
for everyone and precise.
In summary, always try to:
1. Use the active voice
2. Use precise action verbs
3. Avoid verbs that end in -ing
4. Remove unnecessary adverbs and adjectives.
5. Ban these 8 words: obvious, simple, basic, easy, actual, just, clear, and however
6. Use explicit references
7. Use 's to show possession
8. Use the Oxford comma
There are 3 rules to describe classes:
1. Give an overview of the node in the brief description
2. Mention what methods return if it's useful
3. Use "if true" to describe booleans
.. note::
A technical writer's job is to pack as much information as possible into
the smallest and clearest sentences possible. These guidelines will help
you work towards that goal.
.. seealso::
See the :ref:`content guidelines <doc_content_guidelines>` for information
on the types of documentation you can write in the official documentation.
.. _doc_docs_writing_guidelines_clear_english_rules:
7 rules for clear English
-------------------------
Use the active voice
~~~~~~~~~~~~~~~~~~~~
Use the active voice when possible. Take the classes, methods, and
constants you describe as the subject. It's natural to write using the
passive voice, but it's harder to read and produces longer sentences.
.. highlight:: none
Passive:
::
The man **was bitten** by the dog.
Active:
::
The dog bit the man.
**Don't** use the passive voice:
::
void edit_set_pivot ( Vector2 pivot )
[...] This method **is implemented** only in some nodes that inherit Node2D.
**Do** use the node's name as a noun:
::
void edit_set_pivot ( Vector2 pivot )
[...] Only some Node2Ds **implement** this method.
Use precise action verbs
~~~~~~~~~~~~~~~~~~~~~~~~
Favor precise yet common verbs over generic ones like ``make``, ``set``,
and any expression you can replace with a single word.
**Don't** repeat the method's name. It already states it sets the pivot
value to a new one:
::
void edit_set_pivot ( Vector2 pivot )
Set the pivot position of the 2D node to [code]pivot[/code] value. [...]
**Do** explain what's the consequence of this "set": use precise verbs
like ``place``, ``position``, ``rotate``, ``fade``, etc.
::
void edit_set_pivot ( Vector2 pivot )
Position the node's pivot to the [code]pivot[/code] value. [...]
Avoid verbs that end in -ing
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The progressive forms describe continuous actions. E.g. "is calling",
"is moving".
**Don't** use the progressive form for instant changes.
::
Vector2 move ( Vector2 rel_vec )
Move the body in the given direction, **stopping** if there is an obstacle. [...]
**Do** use simple present, past, or future.
::
Vector2 move ( Vector2 rel_vec )
Moves the body in the vector's direction. The body **stops** if it collides with an obstacle. [...]
Exception: If the subject is not clear, replacing "ing" verbs is not an
improvement. For example, in the previous sentence, "it replaces"
would not make much sense where "replacing" currently is.
You may use the progressive tense to describe actions that are
continuous in time. Anything like animation or coroutines.
.. tip::
Verbs can turn into adjectival nouns with -ing. This is not a
conjugation, so you may use them: ``the remaining movement``,
``the missing file``, etc.
Remove unnecessary adverbs and adjectives
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Write as few adjectives and adverbs as possible. Only use them if they
add key information to the description.
**Don't** use redundant or meaningless adverbs. Words that lengthen the
documentation but don't add any information:
::
**Basically** a big texture [...]
**Do** write short sentences in a simple, descriptive language:
::
A big texture [...]
Ban these 8 words
~~~~~~~~~~~~~~~~~
**Don't** ever use these 8 banned words:
1. obvious
2. simple
3. basic
4. easy
5. actual
6. just
7. clear
8. however (some uses)
Game creation and programming aren't simple, and nothing's easy to
someone learning to use the API for the first time. Other words in the
list, like ``just`` or ``actual`` won't add any info to the sentence.
Don't use corresponding adverbs either: obviously, simply, basically,
easily, actually, clearly.
**Don't** example. The banned words lengthen the description and take
attention away from the most important info:
::
**TextureRect**
Control frame that **simply** draws an assigned texture. It can stretch or not. It's a **simple** way to **just** show an image in a UI.
**Do** remove them:
::
**TextureRect**
[Control] node that displays a texture. The texture can stretch to the node's bounding box or stay in the center. Useful to display sprites in your UIs.
"Simple" never helps. Remember, for other users, anything could be
complex or frustrate them. There's nothing like a good old *it's simple*
to make you cringe. Here's the old brief description, the first sentence
on the Timer node's page:
::
**Timer**
A **simple** Timer node.
**Do** explain what the node does instead:
::
**Timer**
Calls a function of your choice after a certain duration.
**Don't** use "basic", it is too vague:
::
**Vector3**
Vector class, which performs **basic** 3D vector math operations.
**Do** use the brief description to offer an overview of the node:
::
**Vector3**
Provides essential math functions to manipulate 3D vectors: cross product, normalize, rotate, etc.
Use explicit references
~~~~~~~~~~~~~~~~~~~~~~~
Favor explicit references over implicit ones.
**Don't** use words like "the former", "the latter", etc. They're not
the most common in English, and they require you to check the reference.
::
[code]w[/code] and [code]h[/code] define right and bottom margins. The **latter** two resize the texture so it fits in the defined margin.
**Do** repeat words. They remove all ambiguity:
::
[code]w[/code] and [code]h[/code] define right and bottom margins. **[code]w[/code] and [code]h[/code]** resize the texture so it fits the margin.
If you need to repeat the same variable name 3 or 4 times, you probably
need to rephrase your description.
Use 's to show possession
~~~~~~~~~~~~~~~~~~~~~~~~~
Avoid "The milk **of** the cow". It feels unnatural in English. Write "The cow's
milk" instead.
**Don't** write "of the X":
::
The region **of the AtlasTexture that is** used.
**Do** use ``'s``. It lets you put the main subject at the start of the
sentence, and keep it short:
::
The **AtlasTexture's** used region.
Use the Oxford comma to enumerate anything
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
From the Oxford dictionary:
The 'Oxford comma' is an optional comma before the word 'and' at the end of a list:
*We sell books, videos, and magazines.*
[...] Not all writers and publishers use it, but it can clarify the meaning of a sentence when the items in a list are not single words:
*These items are available in black and white, red and yellow, and blue and green.*
**Don't** leave the last element of a list without a comma:
::
Create a CharacterBody2D node, a CollisionShape2D node and a sprite node.
**Do** add a comma before `and` or `or`, for the last
element of a list with more than two elements.
::
Create a CharacterBody2D node, a CollisionShape2D node, and a sprite node.
How to write methods and classes
--------------------------------
.. _doc_docs_writing_guidelines_dynamic_typing:
Dynamic vs static typing
~~~~~~~~~~~~~~~~~~~~~~~~
The code examples in the documentation should follow a consistent style not to
confuse users. As static type hints are an optional feature of GDScript, we
chose to stick to writing dynamic code. This leads to writing GDScript that is
concise and accessible.
The exception is topics that explain static typing concepts to users.
**Don't** add a type hint with a colon or by casting:
::
const MainAttack := preload("res://fire_attack.gd")
var hit_points := 5
var name: String = "Bob"
var body_sprite := $Sprite2D as Sprite2D
**Do** write constants and variables with dynamic typing:
::
const MainAttack = preload("res://fire_attack.gd")
var hit_points = 5
var name = "Bob"
var body_sprite = $Sprite2D
**Don't** write functions with inferred arguments or return types:
::
func choose(arguments: PackedStringArray) -> String:
# Chooses one of the arguments from array with equal chances
randomize()
var size := arguments.size()
var choice: int = randi() % size
return arguments[choice]
**Do** write functions using dynamic typing:
::
func choose(arguments):
# Chooses one of the arguments from array with equal chances
randomize()
var size = arguments.size()
var choice = randi() % size
return arguments[choice]
.. _doc_docs_writing_guidelines_real_world_code_example:
Use real-world code examples where appropriate
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Real-world examples are more accessible to beginners than abstract ``foos`` and
``bars``. You can also copy them directly from your game projects, ensuring that
any code snippet compiles without errors.
Writing ``var speed = 10`` rather than ``var my_var = 10`` allows beginners to
understand code better. It gives them a frame of reference as to where they
could use the code snippets in a live project.
**Don't** write made-up examples:
.. code-block:: gdscript
@onready var a = preload("res://MyPath")
@onready var my_node = $MyNode
func foo():
# Do stuff
**Do** write concrete examples:
.. code-block:: gdscript
@onready var sfx_player_gun = preload("res://Assets/Sound/SFXPlayerGun.ogg")
@onready var audio_player = $Audio/AudioStreamPlayer
func play_shooting_sound():
audio_player.stream = sfx_player_gun
audio_player.play()
Of course, there are times when using real-world examples is impractical. In
those situations, you should still avoid using names such as ``my_var``,
``foo()`` or ``my_func()`` and consider more meaningful names for your examples.
Give an overview of the node in the brief description
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The brief description is the reference's most important sentence. It's
the user's first contact with a node:
1. It's the only description in the "Create New Node" dialog.
2. It's at the top of every page in the reference
The brief description should explain the node's role and its
functionality, in up to 200 characters.
**Don't** write tiny and vague summaries:
::
**Node2D**
Base node for 2D system.
**Do** give an overview of the node's functionality:
::
**Node2D**
A 2D game object, inherited by all 2D-related nodes. Has a position, rotation, scale, and Z index.
Use the node's full description to provide more information, and a code
example, if possible.
Mention what methods return if it's useful
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Some methods return important values. Describe them at the end of the
description, ideally on a new line. No need to mention the return values
for any method whose name starts with ``set`` or ``get``.
**Don't** use the passive voice:
::
Vector2 move ( Vector2 rel_vec )
[...] The returned vector is how much movement was remaining before being stopped.
**Do** always use "Returns".
::
Vector2 move ( Vector2 rel_vec )
[...] Returns the remaining movement before the body was stopped.
Notice the exception to the "direct voice" rule: with the move method,
an external collider can influence the method and the body that calls
``move``. In this case, you can use the passive voice.
Use "if true" to describe booleans
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
For boolean member variables, always use ``if true`` and/or
``if false``, to stay explicit. ``Controls whether or not`` may be
ambiguous and won't work for every member variable.
Also, surround boolean values, variable names and methods with ``[code][/code]``.
**Do** start with "if true":
::
Timer.autostart
If [code]true[/code], the timer will automatically start when entering the scene tree.
Use ``[code]`` around arguments
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In the class reference, always surround arguments with ``[code][/code]``. In the
documentation and in Godot, it will display like ``this``. When you edit XML
files in the Godot repository, replace existing arguments written like 'this' or
\`this\` with ``[code]this[/code]``.
.. _doc_docs_writing_guidelines_common_vocabulary:
Common vocabulary to use in Godot's documentation
-------------------------------------------------
The developers chose some specific words to refer to areas of the
interface. They're used in the sources, in the documentation, and you
should always use them instead of synonyms, so the users know what
you're talking about.
.. figure:: img/editor-vocabulary-overview.png
:alt: Overview of the interface and common vocabulary
Overview of the interface and common vocabulary
In the top left corner of the editor lie the ``main menus``. In the
center, the buttons change the ``workspace``. And together the buttons
in the top right are the ``playtest buttons``. The area in the center,
that displays the 2D or the 3D space, is the ``viewport``. At its top,
you find a list of ``tools`` inside the ``toolbar``.
The tabs or dockable panels on either side of the viewport are
``docks``. You have the ``FileSystem dock``, the ``Scene dock`` that
contains your scene tree, the ``Import dock``, the ``Node dock``, and
the ``Inspector`` or ``Inspector dock``. With the default layout you may
call the tabbed docks ``tabs``: the ``Scene tab``, the ``Node tab``...
The Animation, Debugger, etc. at the bottom of the viewport are
``panels``. Together they make up the ``bottom panels``.
Foldable areas of the Inspector are ``sections``. The node's parent
class names, which you can't fold, are ``Classes`` e.g. the
``CharacterBody2D class``. And individual lines with key-value pairs are
``properties``. E.g. ``position`` or ``modulate color`` are both
``properties``.
.. _doc_docs_writing_guidelines_keyboard_shortcuts:
Keyboard shortcut guidelines
----------------------------
Keyboard and mouse shortcuts should make use of the ``:kbd:`` tag, which allows
shortcuts to stand out from the rest of the text and inline code. Use the
compact form for modifier keys (:kbd:`Ctrl`/:kbd:`Cmd`) instead of their spelled
out form (:kbd:`Control`/:kbd:`Command`). For combinations, use the ``+`` symbol
with a space on either side of the symbol.
Make sure to mention shortcuts that differ on macOS compared to other platforms.
You can find a list of all shortcuts, including what they are on macOS, on
:ref:`this page <doc_default_key_mapping>`.
Try to integrate the shortcut into sentences the best you can. Here are some
examples with the ``:kbd:`` tag left as-is for better visibility:
- Press ``:kbd:`Ctrl + Alt + T``` to toggle the panel (``:kbd:`Opt + Cmd + T``` on macOS).
- Press ``:kbd:`Space``` and hold the left mouse button to pan in the 2D editor.
- Press ``:kbd:`Shift + Up Arrow``` to move the node upwards by 8 pixels.
.. _doc_docs_writing_guidelines_manual_style:
Manual style guidelines
-----------------------
Follow these formatting and style guidelines when writing the manual.
Use your best judgement. If you can write more clearly by breaking one of these
guidelines, please do! But remember that the guidelines exist for a reason.
.. note:: In many cases, the manual does not follow these guidelines. If you are
already making changes to a paragraph or section of the docs, update it to
follow these standards. Avoid making unrelated changes that *only* update style,
since every change will require the paragraph to be re-translated.
Text styles
~~~~~~~~~~~
There are a few styles that the manual uses.
+---------------------+--------------------------+------------------------------------------------------------------------+
| Style | RST formatting | Typical usage |
+=====================+==========================+========================================================================+
| Plaintext | ``text`` | Used for most text. |
+---------------------+--------------------------+------------------------------------------------------------------------+
| *Italics* | ``*text*`` | Used for emphasis. Used for introducing new terms. |
+---------------------+--------------------------+------------------------------------------------------------------------+
| **Bold** | ``**text**`` | Used for emphasis, and for editor UI like menus and windows. |
| | | |
+---------------------+--------------------------+------------------------------------------------------------------------+
| ``Code`` | `` text `` | Used for variable names, literal values, and code snippets. ``code`` is|
| | | used in many cases where you would use "quoted plaintext" in typical |
| | | English. |
+---------------------+--------------------------+------------------------------------------------------------------------+
| "Quotes" | ``"text"`` | Used for some literal or quoted values. In many cases, another |
| | | style is preferred. |
+---------------------+--------------------------+------------------------------------------------------------------------+
Emphasis
~~~~~~~~
Use either **bold style** or *italic style* to emphasize words or sentences.
In most cases, either **bold** or *italics* is fine. Use whichever seems best,
or whatever the page already uses.
Prefer using **bold style** for simple emphasis.
- Do **not** close the window without saving first.
Use *italic style* or to emphasize one word in the context of a sentence.
- You can *add* a node to the scene (but you can't connect one).
- You can add a *node* to the scene (but you can't add a resource).
- You can add a node to the *scene* (but you can't add one to a resource).
Use *italic style* when introducing new technical terms. **Bold style**
is fine too.
- Godot uses *nodes* with *scripts* in a *scene tree*.
- Godot uses **nodes** with **scripts** in a **scene tree**.
.. _doc_docs_writing_guidelines_literals:
Literals
~~~~~~~~
Use ``code style`` for literal values. Literals include:
- Integer or ``int`` literals like ``0``, ``-2``, or ``100``
- Float literals like ``0.0``, ``0.5``, ``-2.0``, or ``100.0``
- Vector literals like ``(0.0, 0.0)``, ``(0.5, -0.5, 0.5)``, or ``(1.0, 2.0, 3.0, 4.0)``.
.. _doc_docs_writing_guidelines_class_properties_methods:
Classes, properties, and methods
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Link to classes the first time that you mention them in a page. After the first
mention, use ``code style``. For common classes, like ``Node``, ``Control``, or
``Viewport``, you can also use plaintext.
Link to class members (properties, methods, enums, and constants) the first time
that you mention them in a page. After the first mention, use ``code style``. If
the class member is very common, like a Node2D's ``position``, you don't have to
link.
When discussing properties in the context of the inspector, use **bold style**
instead.
.. _doc_docs_writing_guidelines_editor_ui:
Editor UI
~~~~~~~~~
Use **bold style** for editor UI, including window titles, menus, buttons, input
fields, inspector properties, and inspector sections. Use the exact
capitalization that the editor uses.
- Open the **Editor Settings** window.
- Press the **Confirm** button.
- Change the node's **Transform > Position** property to ``(0, 0)``.
- In the **Project Settings** window, enable the **Advanced Settings** toggle.
Use **Bold > With > Separators** when describing sequence of menus that the
reader must navigate. Use ``>`` as a separator. You can omit ellipses in menu names.
- In **Project > Project Settings > Input Map**, add a new input action.
- Select **Scene > Export As... > MeshLibrary...**.
- Select **Scene > Export As > MeshLibrary**.
.. note:: Sometimes, ``->`` or ``→`` is used as a separator. This is nonstandard.
Replace it with ``>`` if you are already making changes to a section.
.. _doc_docs_writing_guidelines_project_settings:
Project settings
~~~~~~~~~~~~~~~~
Link to individual project settings. Either include the section and subsection
in the link itself, or include the section and subsection separately from the
link. Since long links are not split into multiple lines when the page is
rendered, prefer splitting the setting name and the section when the link is long.
- Set the :ref:`Application > Run > Max FPS<class_ProjectSettings_property_application/run/max_fps>` setting to ``60``.
- In the project settings under **Application > Run**, set :ref:`Max FPS<class_ProjectSettings_property_application/run/max_fps>` to ``60``.
- In **Project Settings > Application > Run**, set :ref:`Max FPS<class_ProjectSettings_property_application/run/max_fps>` to ``60``.
Code blocks and adominitions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Code blocks should use the ``::`` syntax on its own line. Do not use the short
form where it's at the end of a paragraph, as the trailing ``::`` would be included
in the localizable string otherwise. Weblate would show a warning due to the trailing ``::``,
and if the localized string does not end with ``::``, it would break the code block entirely
in the translated manual.
**Bad:**
::
This is a code block::
The code block's contents.
**Good:**
::
This is a code block:
::
The code block's contents.
As for admonitions (note, warning, etc. blocks), you should write the admonition tag on its own line,
then the admonition's contents indented by 4 spaces. Do not write the first line of the contents
on the same line as the admonition tag.
**Bad:**
::
This is an admonition:
.. note:: First line of the note's contents.
Second line of the note's contents.
**Good:**
::
This is an admonition:
.. note::
First line of the note's contents.
Second line of the note's contents.
.. _doc_docs_writing_guidelines_manually_wrapping_lines:
Manually wrapping lines
~~~~~~~~~~~~~~~~~~~~~~~
In the manual, lines must be manually wrapped to no more than 80-100 characters
per line. However, links must not be split into multiple lines, and can exceed
100 characters. Tables can also exceed 100 characters.
When making small changes, you don't need to manually re-wrap the whole paragraph,
as long as the lines don't exceed 100 characters.
**Bad:** Line length exceeds 100 characters:
.. code-block::
The best thing to do is to wrap lines to under 80 characters per line. Wrapping to around 80-90 characters per line is also fine.
If your lines exceed 100 characters, you definitely need to add a newline! Don't forget to remove trailing whitespace when you do.
**Good:** Lines are wrapped to 80-90 characters:
.. code-block::
The best thing to do is to wrap lines to under 80 characters per line. Wrapping to
around 80-90 characters per line is also fine. If your lines exceed 100 characters, you
definitely need to add a newline! Don't forget to remove trailing whitespace when you do.
**Best:** Lines are wrapped to under 80 characters:
.. code-block::
The best thing to do is to wrap lines to under 80 characters per line. Wrapping
to around 80-90 characters per line is also fine. If your lines exceed 100
characters, you definitely need to add a newline! Don't forget to remove
trailing whitespace when you do.
.. tip:: In most text editors, you can add a vertical guide or "ruler" at 80
characters. For example, in Visual Studio Code, you can add the following to
your ``settings.json`` to add rulers at 80 and 100 characters:
.. code:: json
"editor.rulers": [80,100],
Section header syntax
~~~~~~~~~~~~~~~~~~~~~
Use the following syntax for section headers:
.. code-block::
Page title
==========
Renders as h1.
Every page has this.
Section header
--------------
Renders as h2.
Usually appears in sidebar. Many pages only need one level of nested headers.
Sub-section header
~~~~~~~~~~~~~~~~~~
Renders as h3.
Appears in sidebar in some pages, depending on how deeply nested the page is.
Sub-sub-section header
^^^^^^^^^^^^^^^^^^^^^^
Renders as h4.
Usually won't appear in the sidebar.
Currently, there are no cases of deeper header nesting than this. Avoid
introducing any deeper nesting.
Note that headers have no inherent meaning. In reStructuredText, headers are
parsed based on the order that they initially appear within a page. Make sure
that if you use an ``h3`` section header (``~~~``), you include an ``h2``
sub-section header (``---``) first.
See the `Sphinx documentation <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#sections>`__
and the `reStructuredText documentation <https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#sections>`__
for more information.
.. _doc_docs_writing_guidelines_specific_version:
When to refer to a specific Godot version
-----------------------------------------
Most of the time, the class reference and the manual should not specify the first
version in which a feature is added. This is because the documentation describes
the *current* features of the engine. Documentation will be read and maintained
for many versions after it is initially written, and a reference to a first supported
version is only relevant for a few versions after a feature is added. After that,
it becomes historical trivia best left to a dedicated changelog.
Follow these guidelines for when to refer to a specific Godot version:
- If a feature was added in the current major version (4.x), **you can specify**
the feature is new in 4.x.
- If a feature or default approach to a problem was changed between major versions
(3.x -> 4.x), describe the current feature in the main body of the page, and
optionally add a brief sentence or note block to compare 3.x and 4.x.
- If a large feature is added in a 4.x minor version, **you can specify** the minor
version when it was added. Large features have a whole page or large section of
documentation. In many cases it should still be avoided, since it's only relevant
for the next few minor versions.
- If a small feature is added in a 4.x minor version, **do not specify** the minor
version when it was added. Small features have only a short section of
documentation, or are minor additions to existing features.
- If the default approach to a problem is changed in a 4.x minor version, **do
specify** the minor version in which a new default approach was added. For example,
the change from ``TileMap`` to ``TileMapLayer`` in 4.3.
- If a feature was added in a 3.x major or minor version, **do not specify** when
the feature was added. These features are old enough that the exact version
in which they were added is not relevant.
Use roles for editor UI
-----------------------
Much of the manual involves describing a sequence of UI actions in the editor,
like clicking a button, opening a menu, or setting a property in the inspector.
To keep formatting standardized, we use custom Sphinx roles for UI elements.
The following roles are defined:
- ``:button:`` A button, toggle, or other clickable UI element. If the reader
is meant to click on it, and it's not a menu, use this. Renders as
:button:`bold, with a background`.
- ``:menu:`` A series of menus to click through. When listing a series of
menus, separate them with ``>``. Renders as :menu:`bold, with a background`.
- ``:inspector:`` A property *in the inspector*. When describing a property in
*code*, instead either use ``code style`` or link to the property, as
described earlier. Renders as :inspector:`bold`.
- ``:ui:`` A role for any other editor UI elements. Use this if you would have
otherwise just used **bold style**. Use this for input fields, docks, tabs,
windows, bottom panels, etc. Also used for nested project settings or
inspector sections. Renders as :ui:`bold`.
The first two roles, ``:button:`` and ``:menu:`` are used for editor UI that the
reader is meant to click on, and they use an attention-grabbing visual style. The
other roles, ``:inspector:`` and ``:ui:``, are used for other UI and show up
often in text, so they just use bold text to be less distracting.
Our custom roles are inspired by the Sphinx `guilabel <https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-guilabel>`_
and `menuselection <https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-menuselection>`_
roles. However, we use our own implementation to better match the specific needs
of Godot's documentation, using `custom RST roles <https://docutils.sourceforge.io/docs/ref/rst/directives.html#custom-interpreted-text-roles>`_
and some custom CSS.
Examples
~~~~~~~~
These are some example sections that use the roles, in context. Check the source
of this page to see which roles are used.
Adding a sprite and setting some properties
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
In the :ui:`Scene` dock, click :button:`2D Scene` to create a new scene.
Add a new :ref:`Sprite2D <class_Sprite2D>` to the scene by right-clicking on the
root node and choosing :button:`Add Child Node...`. In the :ui:`Create New Node`
window, search for "Sprite2D", select it, and then click :button:`Create`.
On the sprite, under :ui:`Offset`, set :inspector:`Offset` to ``(16, 32)``
and enable :inspector:`Flip H`. Set :inspector:`Animation > HFrames` to ``10``.
In :ui:`CanvasItem > Visibility`, set the :inspector:`Modulate` color to
``ff0000``.
.. tip::
Don't forget to save your scene in :menu:`Scene > Save Scene...`. When the
:ui:`Save Scene As...` window pops up, enter "my_scene.tscn" in the
:ui:`File` field, then click :button:`Save`.
Setting project settings
^^^^^^^^^^^^^^^^^^^^^^^^
Go to :menu:`Project > Project Settings`, then select the
:ref:`Max FPS <class_ProjectSettings_property_application/run/max_fps>`
setting under :ui:`Application > Run`. Don't forget to click the
:button:`Advanced Settings` toggle. Then, in :ui:`Filter Settings`, search for
"physics". Under :ui:`Physics > 3D > Solver`, set
:inspector:`Solver Iterations` to ``16``.
All styles in context
^^^^^^^^^^^^^^^^^^^^^
Use this section to see how the custom roles look, particularly within admonitions.
|styleroles|
.. note::
|styleroles|
.. warning::
|styleroles|
.. danger::
|styleroles|
.. tip::
|styleroles|
.. admonition:: Custom admonition
|styleroles|
.. All the inline roles which are used in the docs. External links don't work in a substitution.
.. |styleroles| replace:: Built-in styles: ``code``, **bold**, and *italics*.
Built-in roles: :kbd:`kbd`, :ref:`ref <doc_about_intro>`, :ref:`ref <class_node>`.
Custom roles: :button:`button`, :menu:`menu > submenu`, :inspector:`inspector`, :ui:`ui`.

18
documentation/guidelines/index.rst Normal file
View File

@@ -0,0 +1,18 @@
:allow_comments: False
.. _doc_contributing_writing_documentation:
Guidelines
==========
Here are the principles and guidelines we strive to follow to write accessible
documentation.
.. toctree::
:maxdepth: 1
:name: toc-contributing-writing-guidelines
content_guidelines
docs_writing_guidelines
docs_image_guidelines
docs_contribution_checklist