From f16fe11ac9b3bf072a7bdef236fcc27c486f5e41 Mon Sep 17 00:00:00 2001
From: Charles Merriam <charles.merriam@gmail.com>
Date: Wed, 11 Feb 2015 20:00:30 -0800
Subject: [PATCH] examples/ - Update docstrings
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Update or create docstrings from many of the examples.  This is part of
the gallery project, as the new docstrings will be the website visible
documentation for the example.   Some changes are to use the main
phrase of ‘the file xx.py’ to include related files on the gallery page.

These are all documentation changes only.
---
 examples/3Drendering/main.py                  | 10 +++----
 examples/application/app_suite.py             | 16 ++++++++---
 examples/application/app_with_kv.py           | 13 ++++++---
 .../application/app_with_kv_in_template1.py   | 15 +++++++----
 examples/canvas/circle.py                     |  3 ++-
 examples/canvas/multitexture.py               | 11 +++++---
 examples/canvas/repeat_texture.py             |  5 +++-
 examples/canvas/tesselate.py                  |  2 +-
 examples/canvas/texture.py                    | 15 +++++++++--
 examples/demo/camera_puzzle.py                | 12 +++++++++
 examples/demo/kivycatalog/main.py             | 21 +++++++++++++++
 examples/demo/multistroke/main.py             | 22 +++++++++++++++
 examples/demo/shadereditor/main.py            | 16 +++++++++++
 examples/demo/showcase/main.py                | 27 +++++++++++++++++++
 examples/demo/touchtracer/main.py             | 19 +++++++++++++
 15 files changed, 180 insertions(+), 27 deletions(-)

diff --git a/examples/3Drendering/main.py b/examples/3Drendering/main.py
index 7e14761815..e840a2d9d6 100644
--- a/examples/3Drendering/main.py
+++ b/examples/3Drendering/main.py
@@ -1,14 +1,14 @@
 '''
-3D Rendering Monkey Head
+3D Rotating Monkey Head
 ========================
 
-This example demonstrates using OpenGL to display rotating monkey head. This
+This example demonstrates using OpenGL to display a rotating monkey head. This
 includes loading a Blender OBJ file, shaders written in OpenGL's Shading
 Language (GLSL), and using scheduled callbacks.
 
-The file monkey.obj is a OBJ file output form the Blender free 3D creation
-software. The file is text, listing vertices and faces. It is loaded
-into a scene using objloader.py's ObjFile class. The file simple.glsl is
+The monkey.obj file is an OBJ file output from the Blender free 3D creation
+software. The file is text, listing vertices and faces and is loaded
+using a class in the file objloader.py. The file simple.glsl is
 a simple vertex and fragment shader written in GLSL.
 '''
 
diff --git a/examples/application/app_suite.py b/examples/application/app_suite.py
index fcca457480..bf117be299 100644
--- a/examples/application/app_suite.py
+++ b/examples/application/app_suite.py
@@ -1,10 +1,18 @@
 '''
-Application Suite
-=================
+Suite of Application Builders
+=============================
+
+This explores different methods of starting an application.  If you run
+this without a command line parameter, you should see a menu in your terminal.
+For example, you can rerun this with 'r' command to pick a random method.
+There are lots of logging options to make this easier to debug:  execution
+order may not be obvious.   Each time you run the command, only one kivy
+application is created.
+
+This uses the file testkvfile.kv and the file app_suite_data/testkvdir.kv.
 
-Explore how applications start. Starts applications one after another,
-waiting for each to be closed first.
 '''
+
 from __future__ import print_function
 import sys
 import re
diff --git a/examples/application/app_with_kv.py b/examples/application/app_with_kv.py
index 48ea45e7df..be5f2cb46e 100644
--- a/examples/application/app_with_kv.py
+++ b/examples/application/app_with_kv.py
@@ -1,9 +1,14 @@
 '''
-Application from a .kv
-======================
+Application built from a  .kv file
+==================================
 
-The root application is created from the corresponding .kv. Check the test.kv
-file to see what will be the root widget.
+This shows how to implicitly use a .kv file for your application.  You
+should see a full screen button labelled "Hello from test.kv".
+
+After Kivy instantiates a subclass of App, it implicitly searches for a .kv
+file.  The file test.kv is selected because the name of the subclass of App is
+TestApp, which implies that kivy should try to load "test.kv".  That file
+contains a root Widget.
 '''
 
 import kivy
diff --git a/examples/application/app_with_kv_in_template1.py b/examples/application/app_with_kv_in_template1.py
index deccb15802..08ccaea3b5 100644
--- a/examples/application/app_with_kv_in_template1.py
+++ b/examples/application/app_with_kv_in_template1.py
@@ -1,11 +1,16 @@
 '''
-Application from a .kv
-======================
+Application from a .kv in a Template Directory
+==============================================
+
+This example shows how you can change the directory for the .kv file. You
+should see "Hello from template1/test.ky" as a button.
+
+As kivy instantiates the TestApp subclass of App, the variable kv_directory
+is set.  Kivy then implicitly searches for a .kv file matching the name
+of the subclass in that directory, finding the file template1/test.kv. That
+file contains a root of class Widget.
 
-The root application is created from the corresponding .kv. Check the test.kv
-file to see what will be the root widget.
 
-This example shows how you can change the directory where the .kv lives.
 '''
 
 import kivy
diff --git a/examples/canvas/circle.py b/examples/canvas/circle.py
index 4b464ffada..694b20b0e8 100644
--- a/examples/canvas/circle.py
+++ b/examples/canvas/circle.py
@@ -5,7 +5,8 @@
 This example exercises circle (ellipse) drawing. You should see sliders at the
 top of the screen with the Kivy logo below it. The sliders control the
 angle start and stop and the height and width scales. There is a button
-to reset the sliders. The entire example is coded in the
+to reset the sliders. The logo used for the circle's background image is
+from the kivy/data directory. The entire example is coded in the
 kv language description.
 '''
 
diff --git a/examples/canvas/multitexture.py b/examples/canvas/multitexture.py
index 58947bcf3f..d6c60232a0 100644
--- a/examples/canvas/multitexture.py
+++ b/examples/canvas/multitexture.py
@@ -2,10 +2,13 @@
 Multitexture Example
 ====================
 
-This example blends two textures:  the letter K in mtexture1.png and an orange
-circle in mtexture2.png. You should see an orange K clipped to a circle.
-It uses a custom shader, written in glsl (OpenGL Shading Language), stored
-in a local string.
+This example blends two textures:  the image mtexture1.png of the letter K
+and the image mtexture2.png of an orange circle. You should see an orange
+K clipped to a circle.  It uses a custom shader, written in glsl
+(OpenGL Shading Language), stored in a local string.
+
+Note the image mtexture1.png is a white 'K' on a transparent background, which
+makes it hard to see.
 '''
 
 from kivy.clock import Clock
diff --git a/examples/canvas/repeat_texture.py b/examples/canvas/repeat_texture.py
index 22bc997834..8bbcdefb76 100644
--- a/examples/canvas/repeat_texture.py
+++ b/examples/canvas/repeat_texture.py
@@ -5,7 +5,10 @@
 This examples repeats the letter 'K' (mtexture1.png) 64 times in a window.
 You should see 8 rows and 8 columns of white K letters, along a label
 showing the current size. As you resize the window, it stays an 8x8.
-This example includes a label on a background.
+This example includes a label with a colored background.
+
+Note the image mtexture1.png is a white 'K' on a transparent background, which
+makes it hard to see.
 '''
 
 from kivy.app import App
diff --git a/examples/canvas/tesselate.py b/examples/canvas/tesselate.py
index 60e8a91ade..8571e10f50 100644
--- a/examples/canvas/tesselate.py
+++ b/examples/canvas/tesselate.py
@@ -4,7 +4,7 @@
 
 This demonstrates the experimental library for tesselating polygons. You
 should see a hollow square with some buttons below it. You can click and
-drag to create additional shapes, watchin the number of vertexes and elements
+drag to create additional shapes, watching the number of vertexes and elements
 at the top of the screen. The 'debug' button toggles showing the mesh in
 different colors.
 '''
diff --git a/examples/canvas/texture.py b/examples/canvas/texture.py
index d55c6b7ae2..3056582900 100644
--- a/examples/canvas/texture.py
+++ b/examples/canvas/texture.py
@@ -1,6 +1,17 @@
 '''
-Example of changing texture properties and the properties
-of its containing rectangle.
+Texture Wrapping and Coordinates Example
+========================================
+
+This example changes texture properties and the properties
+of its containing rectangle.  You should see some a multicolored
+texture with sliders to the left and below and buttons at the
+bottom of the screen.   The image texture_example_image.png is
+rendered into the rectangle.  Sliders change the number of copies of the
+texture (the tex_coords), the size of enclosing rectangle (the taw_height
+and taw_width) while the buttons change how the texture is rendered when more
+than one copy is in the rectangle (the
+texture_wrap).
+
 '''
 
 
diff --git a/examples/demo/camera_puzzle.py b/examples/demo/camera_puzzle.py
index c472b266f7..1558f3419d 100644
--- a/examples/demo/camera_puzzle.py
+++ b/examples/demo/camera_puzzle.py
@@ -1,3 +1,15 @@
+'''
+Shuffled Camera Feed Puzzle
+===========================
+
+This demonstrates using Scatter widgets with a live camera.
+You should see a shuffled grid of rectangles that make up the
+camera feed. You can drag the squares around to see the
+unscrambled camera feed or double click to scramble the grid
+again.
+'''
+
+
 from kivy.app import App
 from kivy.uix.camera import Camera
 from kivy.uix.widget import Widget
diff --git a/examples/demo/kivycatalog/main.py b/examples/demo/kivycatalog/main.py
index 11e3dfd304..3f85789c3a 100755
--- a/examples/demo/kivycatalog/main.py
+++ b/examples/demo/kivycatalog/main.py
@@ -1,4 +1,25 @@
 #!/usr/bin/kivy
+'''
+Kivy Catalog
+============
+
+The Kivy Catalog viewer showcases widgets available in Kivy
+and allows interactive editing of kivy language code to get immediate
+feedback.  You should see a two panel screen with a menu spinner button
+(starting with 'Welcome') and other controls across the top.  The left pane
+contains kivy (.kv) code, and the right side is that code rendered.  You can
+edit the left pane, though changes will be lost when you use the menu
+spinner button.  The catalog will show you dozens of .kv examples controlling
+different widgets and layouts.
+
+The catalog's interface is set in the file kivycatalog.kv, while the
+interfaces for each menu option are set in containers_kvs directory. To
+add a new .kv file to the Kivy Catalog, add a .kv file into the container_kvs
+directory and reference that file in the ScreenManager section of
+kivycatalog.kv.
+
+Known bugs include some issue with the drop
+'''
 import kivy
 kivy.require('1.4.2')
 import os
diff --git a/examples/demo/multistroke/main.py b/examples/demo/multistroke/main.py
index e559fe5960..3fee0ef06d 100644
--- a/examples/demo/multistroke/main.py
+++ b/examples/demo/multistroke/main.py
@@ -1,4 +1,26 @@
 #!/usr/bin/env python
+'''
+Multistroke Recognition Database Demonstration
+==============================================
+
+This application records gestures and attempts to match them.  You should
+see a black drawing surface with some buttons across the bottom.  As you
+make a gesture on the drawing surface, the gesture will be added to
+the history and a match will be attempted.  If you go to the history tab,
+name the gesture, and add it to the database, then simliar gestures in the
+future will be recognized.  You can load and save databases of gestures
+in .kg files.
+
+This demonstration code is many files, with this being the primary file.
+The information pop-up ('No match') comes from the file helpers.py.
+The history pane is managed in the file historymanager.py and described
+in the file historymanager.kv.  The database pane and storage is managed in
+the  file gestureDatabase.py and the described in the file gestureDatabase.kv.
+The general logic of the sliders and buttons are in the file
+settings.py and described in settings.kv. but the actual settings pane is
+described in the file multistroke.kv and managed from this file.
+
+'''
 from kivy.app import App
 from kivy.uix.gridlayout import GridLayout
 from kivy.uix.gesturesurface import GestureSurface
diff --git a/examples/demo/shadereditor/main.py b/examples/demo/shadereditor/main.py
index b3966f9839..059d48cb06 100755
--- a/examples/demo/shadereditor/main.py
+++ b/examples/demo/shadereditor/main.py
@@ -1,4 +1,20 @@
 #!/usr/bin/kivy
+'''
+Live Shader Editor
+==================
+
+This provides a live editor for vertex and fragment editors.
+You should see a window with two editable panes on the left
+and a large kivy logo on the right.  The top pane is the
+Vertex shader and the bottom is the Fragment shader.  The file shadereditor.kv
+describes the interface.
+
+On each keystroke to either shader, declarations are added and the shaders
+are compiled.  If there are no errors, the screen is updated.  Otherwise,
+the error is visible as logging message in your terminal.
+'''
+
+
 import sys
 import kivy
 kivy.require('1.0.6')
diff --git a/examples/demo/showcase/main.py b/examples/demo/showcase/main.py
index 9419397b57..854064de4a 100755
--- a/examples/demo/showcase/main.py
+++ b/examples/demo/showcase/main.py
@@ -1,4 +1,31 @@
 #!/usr/bin/kivy
+'''
+Showcase of Kivy Features
+=========================
+
+This showcases many features of Kivy.   You should see a
+menu bar across the top with a demonstration area below.   The
+first demonstration is the accordion layout.   You can see, but not
+edit, the kv language code for any screen by pressing the bug or
+'show source' icon.   Scroll through the demonstrations using the
+left and right icons in the top right or selecting from the menu
+bar.  This showcases dozens of features.
+
+The file showcase.kv describes the main container, while each demonstration
+pane is described in a separate .kv file in the data/screens directory.
+The image data/background.png provides the gradient background while the
+icons in data/icon directory are used in the control bar.   The file
+data/faust_github.jpg is used in the Scatter pane.  The icons are
+from `http://www.gentleface.com/free_icon_set.html` and licensed as
+Creative Commons - Attribution and Non-commercial Use Only; they
+sell a commercial license.
+
+The file android.txt is used to package the application for use with the
+Kivy Launcher Android application.  For Android devices, you can
+copy/paste this directory into /sdcard/kivy/showcase on your Android device.
+
+'''
+
 from time import time
 from kivy.app import App
 from os.path import dirname, join
diff --git a/examples/demo/touchtracer/main.py b/examples/demo/touchtracer/main.py
index 05949aa8a2..173f26ae5e 100755
--- a/examples/demo/touchtracer/main.py
+++ b/examples/demo/touchtracer/main.py
@@ -1,4 +1,23 @@
 #!/usr/bin/kivy
+'''
+Touch Tracer Line Drawing Demonstration
+=======================================
+
+The demonstrates tracking each touch registered to a device.  You should
+see a basic background image.   When you press and hold the mouse, you
+should see a cross-hairs with the coordinates written next to them.   As
+you drag, it leaves a trail.  Additional information, like pressure,
+will be shown if they are in your device's touch.profile.
+
+This program specifies an icon, the file icon.png, in its App subclass.
+It also uses the particle.png file as source for drawing the trails, which
+white on transparent.  The file touchtracer.kv describes the application.
+
+The file android.txt is used to package the application for use with the
+Kivy Launcher Android application.  For Android devices, you can
+copy/paste this directory into /sdcard/kivy/touchtracer on your Android device.
+
+'''
 __version__ = '1.0'
 
 import kivy