From 6792402014f169f5ff49332721fcbd4cdac15277 Mon Sep 17 00:00:00 2001 From: tetrapod00 <145553014+tetrapod00@users.noreply.github.com> Date: Sat, 9 Nov 2024 22:41:00 -0800 Subject: [PATCH] Add custom Sphinx roles for editor UI --- _static/css/custom.css | 19 ++++ conf.py | 17 +++ .../documentation/docs_writing_guidelines.rst | 101 ++++++++++++++++++ .../step_by_step/nodes_and_scenes.rst | 49 ++++----- 4 files changed, 162 insertions(+), 24 deletions(-) diff --git a/_static/css/custom.css b/_static/css/custom.css index 5a57b8b4a59..0300e8ecd4a 100644 --- a/_static/css/custom.css +++ b/_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); +} diff --git a/conf.py b/conf.py index 939ac5d75af..21d2752e9da 100644 --- a/conf.py +++ b/conf.py @@ -254,6 +254,23 @@ 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 diff --git a/contributing/documentation/docs_writing_guidelines.rst b/contributing/documentation/docs_writing_guidelines.rst index e22829b90b8..8ec975d9ef5 100644 --- a/contributing/documentation/docs_writing_guidelines.rst +++ b/contributing/documentation/docs_writing_guidelines.rst @@ -762,3 +762,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 `_ +and `menuselection `_ +roles. However, we use our own implementation to better match the specific needs +of Godot's documentation, using `custom RST 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 ` 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 ` +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 `, :ref:`ref `. + Custom roles: :button:`button`, :menu:`menu > submenu`, :inspector:`inspector`, :ui:`ui`. diff --git a/getting_started/step_by_step/nodes_and_scenes.rst b/getting_started/step_by_step/nodes_and_scenes.rst index dc8dd119334..4db3dc68029 100644 --- a/getting_started/step_by_step/nodes_and_scenes.rst +++ b/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 ` node, -"3D Scene" adds a :ref:`Node3D ` node, -and "User Interface" adds a :ref:`Control ` node. +root node quickly. :button:`2D Scene` adds a :ref:`Node2D ` node, +:button:`3D Scene` adds a :ref:`Node3D ` node, +and :button:`User Interface` adds a :ref:`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 ` 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.