Merge pull request #10333 from Calinou/bbcode-in-richtextlabel-print-rich

Add a page on the Output bottom panel

Author: mhilbrunner

tutorials/scripting/debug/img/overview_output.webp

@@ -8,6 +8,7 @@ Debug
    :name: toc-learn-features-debug
 
    overview_of_debugging_tools
+   output_panel
    debugger_panel
    the_profiler
    custom_performance_monitors

tutorials/scripting/debug/index.rst

@@ -0,0 +1,93 @@
+.. _doc_output_panel:
+
+Output panel
+============
+
+The output panel is found at the bottom of the screen. Click on **Output** to open it.
+
+.. image:: img/overview_output.webp
+
+The output panel provides several features to make viewing text printed by the
+project (and editor) easier.
+
+.. note::
+
+    The output panel automatically opens when running a project by default.
+    You can control this behavior by changing the **Run > Bottom Panel > Action on Play**
+    editor setting.
+
+Message categories
+------------------
+
+Four message categories are available:
+
+- **Log:** Standard messages printed by the project. Displayed in white or black
+  (depending on the editor theme).
+- **Error:** Messages printed by the project or editor that report important
+  information, but do not indicate a failure. Displayed in yellow.
+- **Warning:** Messages printed by the project or editor that indicate a failure
+  of some kind. Displayed in red.
+- **Editor:** Messages printed by the editor, typically intended to be traces of
+  undo/redo actions. Displayed in gray.
+
+Filtering messages
+------------------
+
+By clicking on the buttons on the right, you can hide certain message categories.
+This can make it easier to find specific messages you're looking for.
+
+You can also filter messages by their text content using the **Filter Messages** box
+at the bottom of the Output panel.
+
+Clearing messages
+-----------------
+
+When running the project, existing messages are automatically cleared by default. This
+is controlled by the **Run > Output > Always Clear Output on Play** editor setting.
+Additionally, you can manually clear messages by clicking the "cleaning brush" icon
+in the top-right corner of the Output panel.
+
+Printing messages
+-----------------
+
+Several methods are available to print messages:
+
+- :ref:`print() <class_@GlobalScope_method_print>`: Prints a message.
+  This method accepts multiple arguments which are concatenated together upon printing.
+- :ref:`print_rich() <class_@GlobalScope_method_print_rich>`: Same as ``print()``,
+  but BBCode can be used to format the text that is printed (see below).
+- :ref:`push_error() <class_@GlobalScope_method_push_error>`: Prints an error message.
+  When an error is printed in a running project, it's displayed in the **Debugger > Errors**
+  tab instead.
+- :ref:`push_warning() <class_@GlobalScope_method_push_warning>`: Prints a warning message.
+  When a warning is printed in a running project, it's displayed in the **Debugger > Errors**
+  tab instead.
+
+To get more advanced formatting capabilities, consider using
+:ref:`doc_gdscript_printf` along with the above printing functions.
+
+.. _doc_output_panel_printing_rich_text:
+
+Printing rich text
+^^^^^^^^^^^^^^^^^^
+
+Using :ref:`print_rich() <class_@GlobalScope_method_print_rich>`, you can print
+rich text to the editor Output panel and standard output (visible when the user
+runs the project from a terminal). This works by converting the BBCode to
+`ANSI escape codes <https://en.wikipedia.org/wiki/ANSI_escape_code>`__ that the
+terminal understands.
+
+In the editor output, all BBCode tags are recognized as usual. In the terminal
+output, only a subset of BBCode tags will work, as documented in the linked
+``print_rich()`` method description above. In the terminal, the colors will look
+different depending on the user's theme, while colors in the editor will use the
+same colors as they would in the project.
+
+.. note::
+
+    ANSI escape code support varies across terminal emulators. On Windows, only
+    Windows 10 and later can display ANSI escape codes in its default terminal
+    application.
+
+    The exact colors displayed in terminal output also depend on the terminal
+    theme chosen by the user.

tutorials/scripting/debug/output_panel.rst

@@ -14,6 +14,12 @@ in the running game.
 Finally, you have options to debug the game running on a remote device
 and to reload changes to your scenes or your code while the game is running.
 
+Output Panel
+--------------
+
+The output panel allows you to see text printed by the project, but also by the editor (e.g. from ``@tool`` scripts).
+You can find information about in :ref:`doc_output_panel`.
+
 Debugger Panel
 --------------
 
@@ -251,7 +257,7 @@ GDScript
 ++++++++
 
 These settings allow you to toggle specific GDScript warnings, such as for
-unused variables. You can also turn off warnings completely. See 
+unused variables. You can also turn off warnings completely. See
 :ref:`doc_gdscript_warning_system` for more information.
 
 Shader Language

tutorials/scripting/debug/overview_of_debugging_tools.rst

@@ -223,6 +223,8 @@ This can be especially useful for plugin and library creators.
     While technically you can use both ``@deprecated`` and ``@experimental`` tags on the same
     class/member, this is not recommended as it is against common conventions.
 
+.. _doc_gdscript_documentation_comments_bbcode_and_class_reference:
+
 BBCode and class reference
 --------------------------
 

tutorials/scripting/gdscript/gdscript_documentation_comments.rst

@@ -21,8 +21,11 @@ scrollbar is automatically displayed if the text does not fit within the
 control's size. The scrollbar can be disabled by unchecking the
 **Scroll Active** property in the RichTextLabel inspector.
 
-Note that the BBCode tags can also be used to some extent in the XML source of
-the class reference. For more information, see :ref:`doc_class_reference_primer`.
+Note that the BBCode tags can also be used to some extent for other use cases:
+
+- BBCode can be used to :ref:`format comments in the XML source of the class reference <doc_class_reference_bbcode>`.
+- BBCode can be used in :ref:`GDScript documentation comments <doc_gdscript_documentation_comments_bbcode_and_class_reference>`.
+- BBCode can be used when :ref:`printing rich text to the Output bottom panel <doc_output_panel_printing_rich_text>`.
 
 .. seealso::