Skip to content

Commit

Permalink
Add section on manual style to Writing Guidelines
Browse files Browse the repository at this point in the history
Specifies when to link to the class reference.
Specifies how to style various kinds of text.
  • Loading branch information
tetrapod00 committed Oct 30, 2024
1 parent f512e1e commit 4bb3745
Showing 1 changed file with 113 additions and 0 deletions.
113 changes: 113 additions & 0 deletions contributing/documentation/docs_writing_guidelines.rst
Original file line number Diff line number Diff line change
Expand Up @@ -507,6 +507,119 @@ examples with the ``:kbd:`` tag left as-is for better visibility:
- 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.


Manual style guidelines
-----------------------

Follow these formatting guidelines while writing documentation. Use your best judgement.
If you can write more clearly by ignoring these guidelines, do so.

.. note:: Much of the existing manual does not follow these guidelines. You don't
have to go out of your way to change existing pages, but do try to bring
pages up to standards when you are already making changes.

Text styles
~~~~~~~~~~~

There are a few styles that the manual uses.


+---------------------+--------------------------+------------------------------------------------------------------------+
| Style | RST formatting | Typical usage |
+=====================+==========================+========================================================================+
| Plaintext | ``Plaintext`` | Used for most text. |
+---------------------+--------------------------+------------------------------------------------------------------------+
| "Quotes" | ``"Quotes"`` | Used for some literal or quoted values. In many cases, another |
| | | style is preferred. |
+---------------------+--------------------------+------------------------------------------------------------------------+
| *Italics* | ``*Italics*`` | Used for emphasis. Used for introducing new terms. |
+---------------------+--------------------------+------------------------------------------------------------------------+
| **Bold** | ``**Bold**`` | Used for emphasis, editor menus and windows, |
| | | and editor navigation paths. |
+---------------------+--------------------------+------------------------------------------------------------------------+
| ``Code`` | `` Code `` | Used for variable names, literal values, and code snippets. ``code`` is|
| | | used in many cases where you would use "quoted plaintext" in typical |
| | | English. |
+---------------------+--------------------------+------------------------------------------------------------------------+


Literals
~~~~~~~~

Literal values use ``code style``.

- Ints: ``0``, ``2``, ``-5``, ``100``.
- Often, floats include the decimal: ``0.0``, ``0.5``, ``2.0``, ``-5.0``, ``1000.0``.
- Often, vectors include the decimal, and have a space between each field: ``(0.0, 0.0)``, ``(0.5, -0.5, 0.5)``, ``(1.0, 2.0, 3.0, 4.0)``.

Classes, properties, and methods
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

When discussing a class, link to the class reference the first time you mention it within a section.
After the first mention of the class, do not link to the class reference. If the class is very common,
like ``Node``, ``Node3D``, ``Control``, or ``Viewport``, you don't have to link. When discussing an instance of
a class, do not link to the class reference.

When mentioning a class property or method, link to the class reference the first time you mention it in a section.
If the class member is very common, like a Node2D's ``position``, you don't have to link. Instead, either style as plaintext
or ``code style``.

Properties
~~~~~~~~~~

Properties are styled differently, depending on whether you are using the inspector
or not.

For properties in the inspector, use either ``code style`` or **bold style**, and
use the name it appears in the inspector. If the property is nested within the
inspector, use the full path.

For properties being used in code example, link to the property the first time it
is mentioned, then use ``code style``.

Editor menus and windows
~~~~~~~~~~~~~~~~~~~~~~~~

Editor menus and windows use **bold style**. Plaintext is also okay, if it's more natural.
For example, use **bold style** when referring specifically to **Project Settings** window,
but use plaintext when referring to the concept of project settings.

**Good**:

- **Editor Settings**
- The **Editor Settings** window.

Editor navigation paths
^^^^^^^^^^^^^^^^^^^^^^^

Editor navigation paths are used to describe a series of menus, submenus, actions,
or buttons that the reader should follow. Navigation paths use **bold** style,
and use ``>``, ``->``, or ```` as a separator, with spaces on both sides.

**Good**:

- **Editor > Editor Settings > Shortcuts**

**Okay**:

- **Editor -> Editor Settings -> Shortcuts**
- **Editor → Editor Settings → Shortcuts**

Project settings
~~~~~~~~~~~~~~~~

Always link to project settings. Either include the full path of the setting in
the link text, or specify the path and the link separately. The setting name
should be ``Title Case``, as it appears in the project settings. The project
setting navigation path is styled as **Bold > With > Arrows**.

**Good**:

- Set :ref:`Max FPS<class_ProjectSettings_property_application/run/max_fps>` in **Project Settings > Application > Run** to ``60``.
- In **Project Settings > Application > Run**, set :ref:`Max FPS<class_ProjectSettings_property_application/run/max_fps>` to ``60``.
- Set the :ref:`ProjectSettings > Application > Run Max FPS<class_ProjectSettings_property_application/run/max_fps>` project setting to ``60``.


When to refer to a specific Godot version
-----------------------------------------

Expand Down

0 comments on commit 4bb3745

Please sign in to comment.