From 240daf555486c38d34e94522c5a8b410908e8829 Mon Sep 17 00:00:00 2001
From: Robin Dunn <robin@alldunn.com>
Date: Thu, 19 May 2016 14:50:04 -0700
Subject: [PATCH] Add a simple docstring for all of the main modules

---
 build.py         |  1 +
 etg/_adv.py      | 10 +++++++---
 etg/_core.py     |  8 ++++++--
 etg/_dataview.py |  8 ++++++--
 etg/_glcanvas.py |  7 ++++---
 etg/_grid.py     |  8 ++++++--
 etg/_html.py     | 11 ++++++++---
 etg/_html2.py    | 13 ++++++++++---
 etg/_media.py    | 10 +++++++---
 etg/_msw.py      |  4 +++-
 etg/_richtext.py |  8 +++++---
 etg/_stc.py      |  9 ++++++---
 etg/_webkit.py   | 10 +++++++---
 etg/_xml.py      |  7 ++++---
 etg/_xrc.py      |  9 +++++----
 15 files changed, 85 insertions(+), 38 deletions(-)

diff --git a/build.py b/build.py
index 73ffb3d4..de1909da 100755
--- a/build.py
+++ b/build.py
@@ -863,6 +863,7 @@ def cmd_etg(options, args):
 
     
 def cmd_sphinx(options, args):
+    from buildtools import mydbstub
     from sphinxtools.postprocess import SphinxIndexes, MakeHeadings, PostProcess, GenGallery
 
     cmdTimer = CommandTimer('sphinx')
diff --git a/etg/_adv.py b/etg/_adv.py
index d4836bcd..4ffc5b33 100644
--- a/etg/_adv.py
+++ b/etg/_adv.py
@@ -3,18 +3,22 @@
 # Author:      Robin Dunn
 #
 # Created:     22-Mar-2012
-# Copyright:   (c) 2013 by Total Control Software
+# Copyright:   (c) 2012-2016 by Total Control Software
 # License:     wxWindows License
 #---------------------------------------------------------------------------
 
 import etgtools
 import etgtools.tweaker_tools as tools
-from etgtools import PyFunctionDef, PyCodeDef, PyPropertyDef
 
 PACKAGE   = "wx" 
 MODULE    = "_adv"
 NAME      = "_adv"   # Base name of the file to generate to for this script
-DOCSTRING = ""
+DOCSTRING = """\
+The ``wx.adv`` module contains classes which are more advanced and/or less
+commonly used than those in the core namespace. They are provided in a
+separate module to help reduce overhead and dependencies for those
+applications which do not need any of these classes.
+"""
 
 # The classes and/or the basename of the Doxygen XML files to be processed by
 # this script. 
diff --git a/etg/_core.py b/etg/_core.py
index 4a570dfe..7db7578e 100644
--- a/etg/_core.py
+++ b/etg/_core.py
@@ -3,7 +3,7 @@
 # Author:      Robin Dunn
 #
 # Created:     8-Nov-2010
-# Copyright:   (c) 2013 by Total Control Software
+# Copyright:   (c) 2010-2016 by Total Control Software
 # License:     wxWindows License
 #---------------------------------------------------------------------------
 
@@ -14,7 +14,11 @@ from etgtools import PyFunctionDef, PyCodeDef, PyPropertyDef
 PACKAGE   = "wx" 
 MODULE    = "_core"
 NAME      = "_core"   # Base name of the file to generate to for this script
-DOCSTRING = ""
+DOCSTRING = """\
+The classes in this module are the most commonly used classes for wxPython,
+which is why they have been made visible in the core ``wx`` namespace.
+Everything you need for building typical GUI applications is here.
+"""
 
 # The classes and/or the basename of the Doxygen XML files to be processed by
 # this script. 
diff --git a/etg/_dataview.py b/etg/_dataview.py
index c7cf6e8e..a70c41b2 100644
--- a/etg/_dataview.py
+++ b/etg/_dataview.py
@@ -3,7 +3,7 @@
 # Author:      Kevin Ollivier
 #
 # Created:     12-Sept-2011
-# Copyright:   (c) 2013 by Kevin Ollivier
+# Copyright:   (c) 2011-2016 by Kevin Ollivier
 # License:     wxWindows License
 #---------------------------------------------------------------------------
 
@@ -13,7 +13,11 @@ import etgtools.tweaker_tools as tools
 PACKAGE   = "wx" 
 MODULE    = "_dataview"
 NAME      = "_dataview"   # Base name of the file to generate to for this script
-DOCSTRING = ""
+DOCSTRING = """\
+The classes in this module provide views and data models for viewing tabular
+or hierarchical data in a more advanced way than what is provided by classes
+such as :ref:`wx.ListCtrl`, :ref:`wx.TreeCtrl`, etc.
+"""
 
 # The classes and/or the basename of the Doxygen XML files to be processed by
 # this script. 
diff --git a/etg/_glcanvas.py b/etg/_glcanvas.py
index 54b113b9..b85c82d4 100644
--- a/etg/_glcanvas.py
+++ b/etg/_glcanvas.py
@@ -3,18 +3,19 @@
 # Author:      Robin Dunn
 #
 # Created:     3-Nov-2012
-# Copyright:   (c) 2013 by Total Control Software
+# Copyright:   (c) 2012-2016 by Total Control Software
 # License:     wxWindows License
 #---------------------------------------------------------------------------
 
 import etgtools
 import etgtools.tweaker_tools as tools
-from etgtools import PyFunctionDef, PyCodeDef, PyPropertyDef
 
 PACKAGE   = "wx" 
 MODULE    = "_glcanvas"
 NAME      = "_glcanvas"   # Base name of the file to generate to for this script
-DOCSTRING = ""
+DOCSTRING = """\
+These classes enable viewing and interacting with an OpenGL context in a wx.Window.
+"""
 
 # The classes and/or the basename of the Doxygen XML files to be processed by
 # this script. 
diff --git a/etg/_grid.py b/etg/_grid.py
index 0e9af160..0ba3e7b6 100644
--- a/etg/_grid.py
+++ b/etg/_grid.py
@@ -3,7 +3,7 @@
 # Author:      Robin Dunn
 #
 # Created:     20-Dec-2012
-# Copyright:   (c) 2013 by Total Control Software
+# Copyright:   (c) 2012-2016 by Total Control Software
 # License:     wxWindows License
 #---------------------------------------------------------------------------
 
@@ -13,7 +13,11 @@ import etgtools.tweaker_tools as tools
 PACKAGE   = "wx" 
 MODULE    = "_grid"
 NAME      = "_grid"   # Base name of the file to generate to for this script
-DOCSTRING = ""
+DOCSTRING = """\
+The Grid and related classes in this module provide functionality similar to a
+spreadsheet, where the application can display rows and columns of data of
+various types, which the user can edit and otherwise interact with.
+"""
 
 # The classes and/or the basename of the Doxygen XML files to be processed by
 # this script. 
diff --git a/etg/_html.py b/etg/_html.py
index 65f65ab5..bbffe08a 100644
--- a/etg/_html.py
+++ b/etg/_html.py
@@ -3,18 +3,23 @@
 # Author:      Robin Dunn
 #
 # Created:     27-Oct-2012
-# Copyright:   (c) 2013 by Total Control Software
+# Copyright:   (c) 2012-2016 by Total Control Software
 # License:     wxWindows License
 #---------------------------------------------------------------------------
 
 import etgtools
 import etgtools.tweaker_tools as tools
-from etgtools import PyFunctionDef, PyCodeDef, PyPropertyDef
 
 PACKAGE   = "wx" 
 MODULE    = "_html"
 NAME      = "_html"   # Base name of the file to generate to for this script
-DOCSTRING = ""
+DOCSTRING = """\
+This module contains a widget class and supporting classes for a generic HTML
+renderer.  It supports only a subset of the HTML standards, and no Javascript
+or CSS, but it is relatively lightweight and has no platform dependencies.  It
+is suitable for displaying simple HTML documents, such as the application's
+documentation or built-in help pages.
+"""
 
 # The classes and/or the basename of the Doxygen XML files to be processed by
 # this script. 
diff --git a/etg/_html2.py b/etg/_html2.py
index 27934fcd..99ec310b 100644
--- a/etg/_html2.py
+++ b/etg/_html2.py
@@ -3,18 +3,25 @@
 # Author:      Robin Dunn
 #
 # Created:     20-Nov-2012
-# Copyright:   (c) 2013 by Total Control Software
+# Copyright:   (c) 2012-2016 by Total Control Software
 # License:     wxWindows License
 #---------------------------------------------------------------------------
 
 import etgtools
 import etgtools.tweaker_tools as tools
-from etgtools import PyFunctionDef, PyCodeDef, PyPropertyDef
+
 
 PACKAGE   = "wx" 
 MODULE    = "_html2"
 NAME      = "_html2"   # Base name of the file to generate to for this script
-DOCSTRING = ""
+DOCSTRING = """\
+The ``wx.html2`` module includes a widget class and supporting classes that
+wraps native browser components on the system, therefore providing a fully
+featured HTML rendering component including the latest HTML, Javascript and
+CSS standards. Since platform-specific back-ends are used (Microsoft Trident,
+WebKit webView, etc.) there will be some difference in ability and behaviors,
+but these classes will minimize those differences as much as possible.
+"""
 
 # The classes and/or the basename of the Doxygen XML files to be processed by
 # this script. 
diff --git a/etg/_media.py b/etg/_media.py
index fa99aa57..2e763bff 100644
--- a/etg/_media.py
+++ b/etg/_media.py
@@ -3,19 +3,23 @@
 # Author:      Dietmar Schwertberger
 #
 # Created:     13-Nov-2015
-# Copyright:   (c) 2015 by Total Control Software
+# Copyright:   (c) 2015-2016 by Total Control Software
 # License:     wxWindows License
 #---------------------------------------------------------------------------
 
 
 import etgtools
 import etgtools.tweaker_tools as tools
-from etgtools import PyFunctionDef, PyCodeDef, PyPropertyDef
 
 PACKAGE   = "wx" 
 MODULE    = "_media"
 NAME      = "_media"   # Base name of the file to generate to for this script
-DOCSTRING = ""
+DOCSTRING = """\
+The ``wx.media`` module provides a widget class that allows displaying various
+types of media, such as video and audio files and streaming, using native
+system components.  The wxWidgets media classes are an optional part of the
+build so it may not always be available on your build of wxPython.
+"""
 
 # The classes and/or the basename of the Doxygen XML files to be processed by
 # this script. 
diff --git a/etg/_msw.py b/etg/_msw.py
index 6fee7bd6..794ccb16 100644
--- a/etg/_msw.py
+++ b/etg/_msw.py
@@ -13,7 +13,9 @@ import etgtools.tweaker_tools as tools
 PACKAGE   = "wx"
 MODULE    = "_msw"
 NAME      = "_msw"  # Base name of the file to generate to for this script
-DOCSTRING = ""
+DOCSTRING = """\
+This module contains a few classes that are only available on Windows.
+"""
 
 # The classes and/or the basename of the Doxygen XML files to be processed by
 # this script.
diff --git a/etg/_richtext.py b/etg/_richtext.py
index 72e960c1..07b5e5fc 100644
--- a/etg/_richtext.py
+++ b/etg/_richtext.py
@@ -3,18 +3,20 @@
 # Author:      Robin Dunn
 #
 # Created:     27-Oct-2012
-# Copyright:   (c) 2015 by Total Control Software
+# Copyright:   (c) 2012-2016 by Total Control Software
 # License:     wxWindows License
 #---------------------------------------------------------------------------
 
 import etgtools
 import etgtools.tweaker_tools as tools
-from etgtools import PyFunctionDef, PyCodeDef, PyPropertyDef
 
 PACKAGE   = "wx" 
 MODULE    = "_richtext"
 NAME      = "_richtext"   # Base name of the file to generate to for this script
-DOCSTRING = ""
+DOCSTRING = """\
+The ``RichTextCtrl`` is a generic, ground-up implementation of a rich text
+control capable of showing multiple text styles and images.
+"""
 
 # The classes and/or the basename of the Doxygen XML files to be processed by
 # this script. 
diff --git a/etg/_stc.py b/etg/_stc.py
index c0544ece..b875b703 100644
--- a/etg/_stc.py
+++ b/etg/_stc.py
@@ -3,18 +3,21 @@
 # Author:      Robin Dunn
 #
 # Created:     24-Oct-2012
-# Copyright:   (c) 2013 by Total Control Software
+# Copyright:   (c) 2012-2016 by Total Control Software
 # License:     wxWindows License
 #---------------------------------------------------------------------------
 
 import etgtools
 import etgtools.tweaker_tools as tools
-from etgtools import PyFunctionDef, PyCodeDef, PyPropertyDef
 
 PACKAGE   = "wx" 
 MODULE    = "_stc"
 NAME      = "_stc"   # Base name of the file to generate to for this script
-DOCSTRING = ""
+DOCSTRING = """\
+The :ref:`wx.stc.StyledTextCrtl` class provided by this module is a text widget
+primarily intended for use as a syntax highlighting source code editor.  It is
+based on the popular Scintilla widget.
+"""
 
 # The classes and/or the basename of the Doxygen XML files to be processed by
 # this script. 
diff --git a/etg/_webkit.py b/etg/_webkit.py
index 8d4d5383..3f1481c0 100644
--- a/etg/_webkit.py
+++ b/etg/_webkit.py
@@ -3,18 +3,22 @@
 # Author:      Robin Dunn
 #
 # Created:     22-Aug-2013
-# Copyright:   (c) 2013 by Total Control Software
+# Copyright:   (c) 2013-2016 by Total Control Software
 # License:     wxWindows License
 #---------------------------------------------------------------------------
 
 import etgtools
 import etgtools.tweaker_tools as tools
-from etgtools import PyFunctionDef, PyCodeDef, PyPropertyDef
 
 PACKAGE   = "wx" 
 MODULE    = "_webkit"
 NAME      = "_webkit"   # Base name of the file to generate to for this script
-DOCSTRING = ""
+DOCSTRING = """\
+The :ref:`wx.webkit.wxWebKitCtrl` and related classes are provided mainly for
+backwards compatibility only. New code would be more future-proof by using the
+``wx.html2`` module.  The classes in this module are light wrappers around
+the OSX WebKit control and is not implemented on any other platform.
+"""
 
 # The classes and/or the basename of the Doxygen XML files to be processed by
 # this script. 
diff --git a/etg/_xml.py b/etg/_xml.py
index 009b8189..d371f453 100644
--- a/etg/_xml.py
+++ b/etg/_xml.py
@@ -3,18 +3,19 @@
 # Author:      Robin Dunn
 #
 # Created:     28-Nov-2012
-# Copyright:   (c) 2013 by Total Control Software
+# Copyright:   (c) 2012-2016 by Total Control Software
 # License:     wxWindows License
 #---------------------------------------------------------------------------
 
 import etgtools
 import etgtools.tweaker_tools as tools
-from etgtools import PyFunctionDef, PyCodeDef, PyPropertyDef
 
 PACKAGE   = "wx" 
 MODULE    = "_xml"
 NAME      = "_xml"   # Base name of the file to generate to for this script
-DOCSTRING = ""
+DOCSTRING = """\
+Some simple XML classes for use with XRC.
+"""
 
 # The classes and/or the basename of the Doxygen XML files to be processed by
 # this script. 
diff --git a/etg/_xrc.py b/etg/_xrc.py
index ad0f1e05..ff12fbe3 100644
--- a/etg/_xrc.py
+++ b/etg/_xrc.py
@@ -3,19 +3,20 @@
 # Author:      Robin Dunn
 #
 # Created:     28-Nov-2012
-# Copyright:   (c) 2013 by Total Control Software
+# Copyright:   (c) 2012-2016 by Total Control Software
 # License:     wxWindows License
 #---------------------------------------------------------------------------
 
 import etgtools
 import etgtools.tweaker_tools as tools
-from etgtools import PyFunctionDef, PyCodeDef, PyPropertyDef,\
-                     ClassDef, MethodDef, ParamDef
+from etgtools import ClassDef, MethodDef, ParamDef
 
 PACKAGE   = "wx" 
 MODULE    = "_xrc"
 NAME      = "_xrc"   # Base name of the file to generate to for this script
-DOCSTRING = ""
+DOCSTRING = """\
+The classes in this module enable loading widgets and layout from XML.
+"""
 
 # The classes and/or the basename of the Doxygen XML files to be processed by
 # this script.