Fix GUI example docstrings (#1758)

* Correct anchor layout example's docstring header

* Add a compliant docstring to box_layout example

* Add compliant top-level docstring to button_with_text gui example

* Add top-level docstring with run command to dropdown gui example

* Add top-level docstring with run command to grid_layout gui example

* Rename password field example file

* Add a top-level docstring with run command to hidden password example

* Add top-level docstring with run command to ninepatch gui example

* Add top-level docstring for scroll_area example

* Add top-level docstring to side_bars_with_box_layout example

* Add top-level docstring to size hint gui example

* Add top-level docstring to the stats_topleft gui example

* Add top-level docstring to style_v2 example

* Add top-level docstring to textured_slider gui example & touch up internal subclass

* Add top-ldevl docstring to toggle gui example

* Add a top-level docstring to widget_gallery gui example

Author: pushfoo

arcade/gui/examples/anchor_layout.py

@@ -1,6 +1,12 @@
 """
-Example shows how to use UIAnchorWidget to position widgets on screen.
-Dummy widgets indicate hovered, pressed and clicked.
+Positioning UI elements with UIAnchorLayout
+
+UIAnchorLayout aligns widgets added to it to directional anchors, which
+include  "left", "center_x", or "top". Dummy widgets react to click events
+by changing color.
+
+If arcade and Python are properly installed, you can run this example with:
+python -m arcade.gui.examples.anchor_layout
 """
 
 import arcade

arcade/gui/examples/box_layout.py

@@ -1,3 +1,13 @@
+"""
+Arrange widgets in vertical or horizontal lines with UIBoxLayout
+
+The direction UIBoxLayout follows is controlled by the `vertical` keyword
+argument. It is True by default. Pass False to it to arrange elements in
+a horizontal line.
+
+If arcade and Python are properly installed, you can run this example with:
+python -m arcade.gui.examples.box_layout
+"""
 import arcade
 from arcade.gui import UIManager, UIBoxLayout
 from arcade.gui.widgets import UIDummy, UISpace

arcade/gui/examples/button_with_text.py

@@ -1,3 +1,13 @@
+"""
+Customizing buttons with text & textures.
+
+This example showcases arcade's range of different built-in button types
+and how they can be used to customize a UI. A UIGridLayout is used to
+arrange buttons.
+
+If arcade and Python are properly installed, you can run this example with:
+python -m arcade.gui.examples.button_with_text
+"""
 import arcade
 from arcade import load_texture
 from arcade.gui import UIManager, UIImage

arcade/gui/examples/dropdown.py

@@ -1,3 +1,12 @@
+"""
+Creating a dropdown menu with UIDropDown
+
+When an option in the UIDropDown is chosen, this example will respond
+by changing the text displayed on screen to reflect it.
+
+If arcade and Python are properly installed, you can run this example with:
+python -m arcade.gui.examples.dropdown
+"""
 import arcade
 from arcade.gui import UIManager, UILabel, UIOnChangeEvent
 from arcade.gui.widgets.dropdown import UIDropdown

arcade/gui/examples/grid_layout.py

@@ -1,3 +1,13 @@
+"""
+Arrange elements in line with grid tiles with UIGridLayout
+
+UIGridLayout allows you to place elements to cover one or more
+cells of a grid. To assign an element more than one grid square,
+use the col_span and row_span keyword arguments.
+
+If arcade and Python are properly installed, you can run this example with:
+python -m arcade.gui.examples.grid_layout
+"""
 import arcade
 from arcade.gui import UIManager
 from arcade.gui.widgets import UIDummy

arcade/gui/examples/login_mask.py renamed to arcade/gui/examples/hidden_password.py

@@ -1,3 +1,13 @@
+"""
+Creating a hidden password field
+
+This example demonstrates how to create a custom text input
+which hides the contents behind a custom character, as often
+required for login screens
+
+If arcade and Python are properly installed, you can run this example with:
+python -m arcade.gui.examples.hidden_password
+"""
 from typing import Optional
 
 import arcade

arcade/gui/examples/ninepatch.py

@@ -1,3 +1,14 @@
+"""
+Create custom scalable UI themes with NinePatchTexture
+
+Nine-patch textures are a technique for scalable custom borders and
+frames for UI elements. Widgets which support a background texture can
+also use a NinePatchTexture to support scaling where the corners stay the
+same, like a window.
+
+If arcade and Python are properly installed, you can run this example with:
+python -m arcade.gui.examples.ninepatch
+"""
 import arcade
 from arcade import load_texture
 from arcade.gui import UIManager, UIAnchorLayout, UIWidget, NinePatchTexture

arcade/gui/examples/scroll_area.py

@@ -1,13 +1,19 @@
 """
-This example is a POC for a UIScrollArea.
+This example is a proof-of-concept for a UIScrollArea.
 
-You can move the UIScrollArea using the mouse wheel or draging it with the middle mouse button
+You can currently scroll through the UIScrollArea in the following ways:
 
-Missing:
-- Thoughtful API
-- UIScrollBars
-"""
+* scrolling the mouse wheel
+* dragging with middle mouse button
+
+It currently needs the following improvements:
 
+* A better API, including scroll direction control
+* UIScrollBars
+
+If arcade and Python are properly installed, you can run this example with:
+python -m arcade.gui.examples.scroll_area
+"""
 from typing import Iterable, Optional
 
 from pyglet.event import EVENT_UNHANDLED

arcade/gui/examples/side_bars_with_box_layout.py

@@ -1,3 +1,17 @@
+"""
+Creating sidebar-like layouts with UIBoxLayout
+
+This example creates left, right, top, and bottom bars by combining the following:
+
+* Placing box layouts inside other box layouts (see the box_layouts example)
+* Size hints (see the size_hints example)
+
+To turn this into a real UI, you  can replace the UIDummy widgets with layout
+objects which contain other widgets.
+
+If arcade and Python are properly installed, you can run this example with:
+python -m arcade.gui.examples.side_bars_with_box_layout
+"""
 import arcade
 from arcade.gui import UIManager, UIDummy, UIBoxLayout
 

arcade/gui/examples/size_hints.py

@@ -1,8 +1,22 @@
 """
-Example shows how to use UIAnchorWidget to position widgets on screen.
-Dummy widgets indicate hovered, pressed and clicked.
-"""
+Sizing widgets using size hint keyword arguments
+
+The following keyword arguments can be used to set preferred size
+information for layouts which arrange widgets
+
+* size_hint
+* size_hint_max
+* size_hint_min
 
+Please note the following:
+
+* These do nothing outside a layout
+* They are only hints, and do not guarantee a specific size will
+  always be set.
+
+If arcade and Python are properly installed, you can run this example with:
+python -m arcade.gui.examples.size_hints
+"""
 import arcade
 from arcade.gui import UIManager, UIBoxLayout
 from arcade.gui.widgets import UIDummy