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 Nov 5, 2024
1 parent f512e1e commit dd090c2
Showing 1 changed file with 96 additions and 0 deletions.
96 changes: 96 additions & 0 deletions contributing/documentation/docs_writing_guidelines.rst
Original file line number Diff line number Diff line change
Expand Up @@ -507,6 +507,102 @@ 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 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 | ``Plaintext`` | Used for most text. |
+---------------------+--------------------------+------------------------------------------------------------------------+
| *Italics* | ``*Italics*`` | Used for emphasis. Used for introducing new terms. |
+---------------------+--------------------------+------------------------------------------------------------------------+
| **Bold** | ``**Bold**`` | Used for emphasis, and for editor UI like menus and windows. |
| | | |
+---------------------+--------------------------+------------------------------------------------------------------------+
| ``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. |
+---------------------+--------------------------+------------------------------------------------------------------------+
| "Quotes" | ``"Quotes"`` | Used for some literal or quoted values. In many cases, another |
| | | style is preferred. |
+---------------------+--------------------------+------------------------------------------------------------------------+


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)``.

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.

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.

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``.

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

Expand Down

0 comments on commit dd090c2

Please sign in to comment.