direct: Improvements to API reference, better cross-linking

direct/src/directbase/DirectStart.py

@@ -4,7 +4,7 @@ opening a graphical window and setting up the scene graph.
 This example demonstrates its use:
 
    import direct.directbase.DirectStart
-   run()
+   base.run()
 
 While it may be considered useful for quick prototyping in the interactive
 Python shell, using it in applications is not considered good style.

direct/src/showbase/Loader.py

@@ -24,14 +24,14 @@ class Loader(DirectObject):
 
     _loadedPythonFileTypes = False
 
-    class Callback:
+    class _Callback:
         """Returned by loadModel when used asynchronously.  This class is
         modelled after Future, and can be awaited."""
 
         # This indicates that this class behaves like a Future.
         _asyncio_future_blocking = False
 
-        class ResultAwaiter(object):
+        class _ResultAwaiter(object):
             """Reinvents generators because of PEP 479, sigh.  See #513."""
 
             __slots__ = 'requestList', 'index'
@@ -126,9 +126,9 @@ class Loader(DirectObject):
                 self._asyncio_future_blocking = True
 
             if self.gotList:
-                return self.ResultAwaiter([self])
+                return self._ResultAwaiter([self])
             else:
-                return self.ResultAwaiter(self.requestList)
+                return self._ResultAwaiter(self.requestList)
 
         def __aiter__(self):
             """ This allows using `async for` to iterate asynchronously over
@@ -138,7 +138,7 @@ class Loader(DirectObject):
             requestList = self.requestList
             assert requestList is not None, "Request was cancelled."
 
-            return self.ResultAwaiter(requestList)
+            return self._ResultAwaiter(requestList)
 
     # special methods
     def __init__(self, base):
@@ -308,7 +308,7 @@ class Loader(DirectObject):
             # requested models have been loaded, we'll invoke the
             # callback (passing it the models on the parameter list).
 
-            cb = Loader.Callback(self, len(modelList), gotList, callback, extraArgs)
+            cb = Loader._Callback(self, len(modelList), gotList, callback, extraArgs)
             i = 0
             for modelPath in modelList:
                 request = self.loader.makeAsyncRequest(Filename(modelPath), loaderOptions)
@@ -476,7 +476,7 @@ class Loader(DirectObject):
             # requested models have been saved, we'll invoke the
             # callback (passing it the models on the parameter list).
 
-            cb = Loader.Callback(self, len(modelList), gotList, callback, extraArgs)
+            cb = Loader._Callback(self, len(modelList), gotList, callback, extraArgs)
             i = 0
             for modelPath, node in modelList:
                 request = self.loader.makeAsyncSaveRequest(Filename(modelPath), loaderOptions, node)
@@ -1013,7 +1013,7 @@ class Loader(DirectObject):
             # requested sounds have been loaded, we'll invoke the
             # callback (passing it the sounds on the parameter list).
 
-            cb = Loader.Callback(self, len(soundList), gotList, callback, extraArgs)
+            cb = Loader._Callback(self, len(soundList), gotList, callback, extraArgs)
             for i, soundPath in enumerate(soundList):
                 request = AudioLoadRequest(manager, soundPath, positional)
                 request.setDoneEvent(self.hook)
@@ -1078,7 +1078,7 @@ class Loader(DirectObject):
             callback = self.__asyncFlattenDone
             gotList = True
 
-        cb = Loader.Callback(self, len(modelList), gotList, callback, extraArgs)
+        cb = Loader._Callback(self, len(modelList), gotList, callback, extraArgs)
         i = 0
         for model in modelList:
             request = ModelFlattenRequest(model.node())

direct/src/showbase/Messenger.py

@@ -1,5 +1,5 @@
 """This defines the Messenger class, which is responsible for most of the
-event handling that happens on the Python side.
+:ref:`event handling <event-handlers>` that happens on the Python side.
 """
 
 __all__ = ['Messenger']

direct/src/showbase/ShowBase.py

@@ -1,4 +1,4 @@
-""" This module contains ShowBase, an application framework responsible
+""" This module contains `.ShowBase`, an application framework responsible
 for opening a graphical display, setting up input devices and creating
 the scene graph.
 
@@ -19,14 +19,15 @@ 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.
+they are accessible to any Python module, without the need fors extra imports.
 
 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
+Refer to the :mod:`builtins` page for a listing of the variables written to the
-:mod:`~direct.showbase.ShowBaseGlobal` module.
+built-in scope.
+
 """
 
 __all__ = ['ShowBase', 'WindowControls']
@@ -2022,7 +2023,7 @@ class ShowBase(DirectObject.DirectObject):
     def enableAllAudio(self):
         """
         Reenables the SFX and music managers that were active at the time
-        `disableAllAudio() was called.  Meant to be called when the app regains
+        `disableAllAudio()` was called.  Meant to be called when the app regains
         audio focus.
         """
         self.AppHasAudioFocus = 1

direct/src/showbase/ShowBaseGlobal.py

@@ -2,9 +2,14 @@
 :class:`~.ShowBase.ShowBase` instance, as an alternative to using the builtin
 scope.
 
-Note that you cannot directly import `base` from this module since ShowBase
+Many of the variables contained in this module are also automatically written
-may not have been created yet; instead, ShowBase dynamically adds itself to
+to the :mod:`builtins` module when ShowBase is instantiated, making them
-this module's scope when instantiated."""
+available to any Python code.  Importing them from this module instead can make
+it easier to see where these variables are coming from.
+
+Note that you cannot directly import :data:`~builtins.base` from this module
+since ShowBase may not have been created yet; instead, ShowBase dynamically
+adds itself to this module's scope when instantiated."""
 
 __all__ = []
 
@@ -17,8 +22,8 @@ from . import DConfig as config
 
 __dev__ = config.GetBool('want-dev', __debug__)
 
-#: The global instance of the :class:`~panda3d.core.VirtualFileSystem`, as
+#: The global instance of the :ref:`virtual-file-system`, as obtained using
-#: obtained using :meth:`panda3d.core.VirtualFileSystem.getGlobalPtr()`.
+#: :meth:`panda3d.core.VirtualFileSystem.getGlobalPtr()`.
 vfs = VirtualFileSystem.getGlobalPtr()
 
 #: The default Panda3D output stream for notifications and logging, as