godotengine/godot-docs
1
0
Fork 0
mirror of https://github.com/godotengine/godot-docs.git synced 2025-12-31 17:49:03 +03:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #10251 from tetrapod00/custom-role

Browse Source 
Add custom Sphinx roles for editor UI
This commit is contained in:
Matthew
2025-07-15 06:51:03 -04:00
committed by GitHub
parent 089d35e6d8 6792402014
commit 76cf579d9e
4 changed files with 162 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files

19
_static/css/custom.css
View File

@@ -150,6 +150,8 @@
--kbd-shadow-color: #b0b7bf;
--kbd-text-color: #444d56;
--role-button-background-color: #d3d7e1;
--code-example-good-color: #3fb950;
--code-example-bad-color: #f85149;
@@ -279,6 +281,8 @@
--kbd-outline-color: #3d4144;
--kbd-shadow-color: #1e2023;
--kbd-text-color: #e2f2ff;
--role-button-background-color: #22252d;
--code-example-good-color: #3fb950;
--code-example-bad-color: #f85149;
@@ -1844,3 +1848,18 @@ p + .classref-constant {
#godot-giscus {
margin-bottom: 1em;
}
/* Custom Sphinx roles for editor UI */
/* The :ui: and :inspector: roles just render as bold. */
.role-ui {
font-weight: 700;
}
.role-button, .role-menu {
font-size: 80%;
border-radius: 4px;
padding: 2.4px 6px;
margin: auto 2px;
border: 0px solid #7fbbe3;
background: var(--role-button-background-color);
}

17
conf.py
View File

@@ -231,6 +231,23 @@ linkcheck_anchors = False
linkcheck_timeout = 10
# -- Custom Sphinx roles for UI -------------------------------------------
rst_prolog = """
.. role:: button
:class: role-button role-ui
.. role:: menu
:class: role-menu role-ui
.. role:: inspector
:class: role-ui
.. role:: ui
:class: role-ui
"""
# -- I18n settings --------------------------------------------------------
# Godot localization is handled via https://github.com/godotengine/godot-docs-l10n

101
contributing/documentation/docs_writing_guidelines.rst
View File

@@ -814,3 +814,104 @@ Follow these guidelines for when to refer to a specific Godot version:
- 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`.

49
getting_started/step_by_step/nodes_and_scenes.rst
View File

@@ -73,23 +73,24 @@ opening the project, you should see an empty editor.
.. image:: img/nodes_and_scenes_01_empty_editor.webp
In an empty scene, the Scene dock on the left shows several options to add a
root node quickly. "2D Scene" adds a :ref:`Node2D <class_Node2D>` node,
"3D Scene" adds a :ref:`Node3D <class_Node3D>` node,
and "User Interface" adds a :ref:`Control <class_Control>` node.
root node quickly. :button:`2D Scene` adds a :ref:`Node2D <class_Node2D>` node,
:button:`3D Scene` adds a :ref:`Node3D <class_Node3D>` node,
and :button:`User Interface` adds a :ref:`Control <class_Control>` node.
These presets are here for convenience; they are not mandatory.
"Other Node" lets you select any node to be the root node.
In an empty scene, "Other Node" is equivalent to pressing the "Add Child Node"
:button:`Other Node` lets you select any node to be the root node.
In an empty scene, :button:`Other Node` is equivalent to pressing the :button:`Add Child Node`
button at the top-left of the Scene dock, which usually adds
a new node as a child of the currently selected node.
We're going to add a single :ref:`Label <class_Label>` node to our scene. Its function is to draw
text on the screen.
Press the "Add Child Node" button or "Other Node" to create a root node.
Press the :button:`Add Child Node` button or :button:`Other Node` to create a
root node.
.. image:: img/nodes_and_scenes_02_scene_dock.webp
The Create Node dialog opens, showing the long list of available nodes.
The :ui:`Create New Node` dialog opens, showing the long list of available nodes.
.. image:: img/nodes_and_scenes_03_create_node_window.webp
@@ -97,8 +98,8 @@ Select the Label node. You can type its name to filter down the list.
.. image:: img/nodes_and_scenes_04_create_label_window.webp
Click on the Label node to select it and click the Create button at the bottom
of the window.
Click on the Label node to select it and click the :button:`Create` button at
the bottom of the window.
.. image:: img/nodes_and_scenes_05_editor_with_label.webp
@@ -110,11 +111,11 @@ and the node's properties appear in the Inspector dock on the right.
Changing a node's properties
----------------------------
The next step is to change the Label's "Text" property. Let's change it to
"Hello World".
The next step is to change the Label's :inspector:`Text` property. Let's change
it to "Hello World".
Head to the Inspector dock on the right of the viewport. Click inside the field
below the Text property and type "Hello World".
below the :inspector:`Text` property and type "Hello World".
.. image:: img/nodes_and_scenes_06_label_text.webp
@@ -137,17 +138,18 @@ move it to the center of the view delimited by the rectangle.
Running the scene
-----------------
Everything's ready to run the scene! Press the **Run Current Scene** button in
the top-right of the screen or press :kbd:`F6` (:kbd:`Cmd + R` on macOS).
Everything's ready to run the scene! Press the :button:`Run Current Scene`
button in the top-right of the screen or press :kbd:`F6` (:kbd:`Cmd + R` on
macOS).
.. image:: img/nodes_and_scenes_09_play_scene_button.webp
A popup invites you to save the scene, which is required to run it.
Click the Save button in the file browser to save it as ``label.tscn``.
A popup invites you to save the scene, which is required to run it. Click the
:button:`Save` button in the file browser to save it as ``label.tscn``.
.. image:: img/nodes_and_scenes_10_save_scene_as.webp
.. note:: The Save Scene As dialog, like other file dialogs in the editor, only
.. note:: The :ui:`Save Scene As` dialog, like other file dialogs in the editor, only
allows you to save files inside the project. The ``res://`` path at
the top of the window represents the project's root directory and
stands for "resource path". For more information about file paths in
@@ -162,8 +164,8 @@ Close the window or press :kbd:`F8` (:kbd:`Cmd + .` on macOS) to quit the runnin
Setting the main scene
----------------------
To run our test scene, we used the **Run Current Scene** button. Another button
next to it, **Run Project**, allows you to set and run the project's
To run our test scene, we used the :button:`Run Current Scene` button. Another button
next to it, :button:`Run Project`, allows you to set and run the project's
**main scene**. You can also press :kbd:`F5` (:kbd:`Cmd + B` on macOS) to do so.
.. image:: img/nodes_and_scenes_12_play_button.webp
@@ -176,8 +178,8 @@ A popup window appears and invites you to select the main scene.
.. image:: img/nodes_and_scenes_13_main_scene_popup.webp
Click the Select button, and in the file dialog that appears, double click on
``label.tscn``.
Click the :button:`Select` button, and in the file dialog that appears, double
click on ``label.tscn``.
.. image:: img/nodes_and_scenes_14_select_main_scene.webp
@@ -186,9 +188,8 @@ will use this scene as a starting point.
.. note:: The editor saves the main scene's path in a project.godot file in your
project's directory. While you can edit this text file directly to
change project settings, you can also use the "Project -> Project
Settings" window to do so. For more information, see
:ref:`doc_project_settings`.
change project settings, you can also use the :menu:`Project > Project Settings`
window to do so. For more information, see :ref:`doc_project_settings`.
In the next part, we will discuss another key concept in games and in Godot:
creating instances of a scene.