From 3cf69e111362001c76b66221c9db18268f8a468c Mon Sep 17 00:00:00 2001
From: Yuri Sizov <yuris@humnom.net>
Date: Mon, 16 Aug 2021 17:31:25 +0300
Subject: [PATCH] Reorganize user interface tutorials

---
 .../introduction_to_editor_development.rst    |  2 +-
 tutorials/ui/index.rst                        | 58 +++++++++++++++++--
 2 files changed, 55 insertions(+), 5 deletions(-)

diff --git a/development/editor/introduction_to_editor_development.rst b/development/editor/introduction_to_editor_development.rst
index 7694a169f..892bc4896 100644
--- a/development/editor/introduction_to_editor_development.rst
+++ b/development/editor/introduction_to_editor_development.rst
@@ -22,7 +22,7 @@ Technical choices
 -----------------
 
 The Godot editor is drawn using Godot's renderer and
-:ref:`UI system <toc-learn-features-gui>`. It does *not* rely on a toolkit
+:ref:`UI system <doc_user_interface>`. It does *not* rely on a toolkit
 such as GTK or Qt. This is similar in spirit to software like Blender.
 While using toolkits makes it easier to achieve a "native" appearance, they are
 also quite heavy and their licensing is not compatible with Godot's.
diff --git a/tutorials/ui/index.rst b/tutorials/ui/index.rst
index 4d8467701..6fdd6d92b 100644
--- a/tutorials/ui/index.rst
+++ b/tutorials/ui/index.rst
@@ -1,13 +1,63 @@
+.. _doc_user_interface:
+
 User Interface (UI)
 ===================
 
+In this section of the tutorial we explain the basics of creating a graphical
+user interface (GUI) in Godot.
+
+UI building blocks
+------------------
+
+Like everything else in Godot the user interface is built using nodes, specifically
+:ref:`Control <class_Control>` nodes. There are many different types of controls
+which are useful for creating specific types of the GUI. For simplicity we can
+separate them into two groups: content and layout.
+
+Typical content controls include:
+
+* :ref:`Buttons <class_Button>`
+* :ref:`Labels <class_Label>`
+* :ref:`LineEdits <class_LineEdit>` and :ref:`TextEdits <class_TextEdit>`
+
+Typical layout controls include:
+
+* :ref:`BoxContainers <class_BoxContainer>`
+* :ref:`MarginContainers <class_MarginContainer>`
+* :ref:`ScrollContainers <class_ScrollContainer>`
+* :ref:`TabContainers <class_TabContainer>`
+* :ref:`Popups <class_Popup>`
+
+The following pages explain the basics of using such controls.
+
 .. toctree::
    :maxdepth: 1
-   :name: toc-learn-features-gui
+   :name: toc-gui-basics
 
-   gui_skinning
-   custom_gui_controls
    size_and_anchors
    gui_containers
-   bbcode_in_richtextlabel
+   custom_gui_controls
    control_node_gallery
+
+GUI skinning and themes
+-----------------------
+
+Godot features an in-depth skinning/theming system for control nodes. The pages in this section
+explain the benefits of that system and how to set it up in your projects.
+
+.. toctree::
+   :maxdepth: 1
+   :name: toc-gui-skinning
+
+   gui_skinning
+
+Control node tutorials
+----------------------
+
+The following articles cover specific details of using particular control nodes.
+
+.. toctree::
+   :maxdepth: 1
+   :name: toc-control-nodes-tutorials
+
+   bbcode_in_richtextlabel