showbase: improve docstrings of ShowBase and ShowBaseGlobal

direct/src/showbase/ShowBase.py

@@ -1,6 +1,33 @@
 """ This module contains ShowBase, an application framework responsible
 for opening a graphical display, setting up input devices and creating
-the scene graph. """
+the scene graph.
+
+The simplest way to open a ShowBase instance is to execute this code:
+
+.. code-block:: python
+
+   from direct.showbase.ShowBase import ShowBase
+
+   base = ShowBase()
+   base.run()
+
+A common approach is to create your own subclass inheriting from ShowBase.
+
+Built-in global variables
+-------------------------
+
+Some key variables used in all Panda3D scripts are actually attributes of the
+ShowBase instance.  When creating an instance of this class, it will write many
+of these variables to the built-in scope of the Python interpreter, so that
+they are accessible to any Python module.
+
+While these are handy for prototyping, we do not recommend using them in bigger
+projects, as it can make the code confusing to read to other Python developers,
+to whom it may not be obvious where these variables are originating.
+
+Some of these built-in variables are documented further in the
+:mod:`~direct.showbase.ShowBaseGlobal` module.
+"""
 
 __all__ = ['ShowBase', 'WindowControls']
 
@@ -1110,8 +1137,8 @@ class ShowBase(DirectObject.DirectObject):
         2-d objects and gui elements that are superimposed over the
         3-d geometry in the window.
         """
-        # We've already created aspect2d in ShowBaseGlobal, for the
-        # benefit of creating DirectGui elements before ShowBase.
+        # We've already created render2d and aspect2d in ShowBaseGlobal,
+        # for the benefit of creating DirectGui elements before ShowBase.
         from . import ShowBaseGlobal
 
         ## This is the root of the 2-D scene graph.
@@ -1135,10 +1162,6 @@ class ShowBase(DirectObject.DirectObject):
         self.render2d.setMaterialOff(1)
         self.render2d.setTwoSided(1)
 
-        # We've already created aspect2d in ShowBaseGlobal, for the
-        # benefit of creating DirectGui elements before ShowBase.
-        from . import ShowBaseGlobal
-
         ## The normal 2-d DisplayRegion has an aspect ratio that
         ## matches the window, but its coordinate system is square.
         ## This means anything we parent to render2d gets stretched.

direct/src/showbase/ShowBaseGlobal.py

@@ -17,17 +17,39 @@ from . import DConfig as config
 
 __dev__ = config.GetBool('want-dev', __debug__)
 
-#: The global instance of the :class:`panda3d.core.VirtualFileSystem`.
+#: The global instance of the :class:`~panda3d.core.VirtualFileSystem`, as
+#: obtained using :meth:`panda3d.core.VirtualFileSystem.getGlobalPtr()`.
 vfs = VirtualFileSystem.getGlobalPtr()
+
+#: The default Panda3D output stream for notifications and logging, as
+#: obtained using :meth:`panda3d.core.Notify.out()`.
 ostream = Notify.out()
+
+#: The clock object used by default for rendering and animation, obtained using
+#: :meth:`panda3d.core.ClockObject.getGlobalClock()`.
 globalClock = ClockObject.getGlobalClock()
+
+#: See :meth:`panda3d.core.ConfigPageManager.getGlobalPtr()`.
 cpMgr = ConfigPageManager.getGlobalPtr()
+
+#: See :meth:`panda3d.core.ConfigVariableManager.getGlobalPtr()`.
 cvMgr = ConfigVariableManager.getGlobalPtr()
+
+#: See :meth:`panda3d.core.PandaSystem.getGlobalPtr()`.
 pandaSystem = PandaSystem.getGlobalPtr()
 
-# This is defined here so GUI elements can be instantiated before ShowBase.
+#: The root of the 2-D scene graph.  The coordinate system of this node runs
+#: from -1 to 1, with the X axis running from left to right and the Z axis from
+#: bottom to top.
 render2d = NodePath("render2d")
+
+#: The root of the 2-D scene graph used for GUI rendering.  Unlike render2d,
+#: which may result in elements being stretched in windows that do not have a
+#: square aspect ratio, this node is scaled automatically to ensure that nodes
+#: parented to it do not appear stretched.
 aspect2d = render2d.attachNewNode(PGTop("aspect2d"))
+
+#: A dummy scene graph that is not being rendered by anything.
 hidden = NodePath("hidden")
 
 # Set direct notify categories now that we have config