Merge pull request #10251 from tetrapod00/custom-role

Add custom Sphinx roles for editor UI

_static/css/custom.css

@@ -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);
+}

conf.py

@@ -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

contributing/documentation/docs_writing_guidelines.rst

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

getting_started/step_by_step/nodes_and_scenes.rst

@@ -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,
+root node quickly. :button:`2D Scene` adds a :ref:`Node2D <class_Node2D>` node,
-"3D Scene" adds a :ref:`Node3D <class_Node3D>` node,
+:button:`3D Scene` adds a :ref:`Node3D <class_Node3D>` node,
-and "User Interface" adds a :ref:`Control <class_Control>` 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.
+:button:`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"
+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
+Click on the Label node to select it and click the :button:`Create` button at
-of the window.
+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
+The next step is to change the Label's :inspector:`Text` property. Let's change
-"Hello World".
+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 
+Everything's ready to run the scene! Press the :button:`Run Current Scene`
-the top-right of the screen or press :kbd:`F6` (:kbd:`Cmd + R` on macOS).
+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.
+A popup invites you to save the scene, which is required to run it. Click the
-Click the Save button in the file browser to save it as ``label.tscn``.
+: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 
+To run our test scene, we used the :button:`Run Current Scene` button. Another button 
-next to it, **Run Project**, allows you to set and run the project's 
+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
+Click the :button:`Select` button, and in the file dialog that appears, double
-``label.tscn``.
+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
+          change project settings, you can also use the :menu:`Project > Project Settings`
-          Settings" window to do so. For more information, see
+          window to do so. For more information, see :ref:`doc_project_settings`.
-          :ref:`doc_project_settings`.
 
 In the next part, we will discuss another key concept in games and in Godot:
 creating instances of a scene.