Docs: Pyglet window

Author: einarf

demosys/context/pyglet/keys.py

@@ -5,7 +5,9 @@
 
 
 class Keys(BaseKeys):
-    """Namespace translating pyglet keys"""
+    """
+    Namespace mapping pyglet specific key constants
+    """
     ESCAPE = key.ESCAPE
     SPACE = key.SPACE
     ENTER = key.ENTER

demosys/context/pyglet/window.py

@@ -1,4 +1,5 @@
 import platform
+import os
 
 import moderngl
 import pyglet
@@ -8,7 +9,7 @@
 
 from .keys import Keys
 
-if platform.system() == "Darwin":
+if platform.system() == "Darwin" and not os.environ.get('DOCS_BUILDING'):
     raise RuntimeError((
         "Pyglet do not support OpenGL core contexts "
         "and will only be able to support version 2.1 on OS X.\n"
@@ -17,9 +18,19 @@
 
 
 class Window(BaseWindow):
+    """
+    Window based on pyglet.
+
+    Note that pylget is unable to make core 3.3+ contexts
+    and will not work for certain drivers and enviroments such as on OS X.
+    """
     keys = Keys
 
     def __init__(self):
+        """
+        Opens a window using pyglet, registers input callbacks
+        and creates a moderngl context.
+        """
         super().__init__()
         # Disable all error checking
         pyglet.options['debug_gl'] = False
@@ -55,16 +66,31 @@ def __init__(self):
         self.set_default_viewport()
 
     def on_key_press(self, symbol, modifiers):
+        """
+        Pyglet specific key press callback.
+        Forwards and translates the events to :py:func:`keyboard_event`
+        """
         self.keyboard_event(symbol, self.keys.ACTION_PRESS, modifiers)
 
     def on_key_release(self, symbol, modifiers):
+        """
+        Pyglet specific key release callback.
+        Forwards and translates the events to :py:func:`keyboard_event`
+        """
         self.keyboard_event(symbol, self.keys.ACTION_RELEASE, modifiers)
 
     def on_mouse_motion(self, x, y, dx, dy):
+        """
+        Pyglet specific mouse motion callback.
+        Forwards and traslates the event to :py:func:`cursor_event`
+        """
         # screen coordinates relative to the lower-left corner
         self.cursor_event(x, self.buffer_height - y, dx, dy)
 
     def on_resize(self, width, height):
+        """
+        Pyglet specific callback for window resize events.
+        """
         self.width, self.height = width, height
         self.buffer_width, self.buffer_height = width, height
         self.resize(width, height)
@@ -74,21 +100,32 @@ def use(self):
         self.fbo.use()
 
     def swap_buffers(self):
-        # Ensure the context is present
+        """
+        Swap buffers, increment frame counter and pull events
+        """
         if not self.window.context:
             return
 
         self.frames += 1
         self.window.flip()
         self.window.dispatch_events()
 
-    def should_close(self):
+    def should_close(self) -> bool:
+        """
+        returns the ``has_exit`` state in the pyglet window
+        """
         return self.window.has_exit
 
     def close(self):
+        """
+        Sets the close state in the pyglet window
+        """
         self.window.close()
 
     def terminate(self):
+        """
+        No cleanup is really needed. Empty method
+        """
         pass
 
 

docs/conf.py

@@ -35,7 +35,7 @@ class Mock(MagicMock):
     def __getattr__(cls, name):
         return MagicMock()
 
-MOCK_MODULES = ['glfw',]
+MOCK_MODULES = ['glfw', 'pyglet', 'pyglet.window']
 sys.modules.update((mod_name, Mock()) for mod_name in MOCK_MODULES)
 
 # Define a settings module

docs/reference/demosys.context.pyglet.rst

@@ -0,0 +1,27 @@
+
+.. py:module:: demosys.context.pyglet
+.. py:currentmodule:: demosys.context.pyglet
+
+demosys.context.pyglet.Window
+=============================
+
+.. autodata:: Window
+
+.. autodata:: Keys
+
+Methods
+-------
+
+.. automethod:: Window.__init__
+.. automethod:: Window.on_key_press
+.. automethod:: Window.on_key_release
+.. automethod:: Window.on_mouse_motion
+.. automethod:: Window.on_resize
+.. automethod:: Window.use
+.. automethod:: Window.swap_buffers
+.. automethod:: Window.should_close
+.. automethod:: Window.close
+.. automethod:: Window.terminate
+
+Attributes
+----------

docs/reference/index.rst

@@ -18,3 +18,4 @@ Reference
    demosys.context.base
    demosys.context.glfw
    demosys.context.headless
+   demosys.context.pyglet