Doc cleanup

Author: einarf

README.md

@@ -89,7 +89,7 @@ Running tests:
 pytest
 ```
 
-Bulding docs:
+Building docs:
 
 ```bash
 python setup.py build_sphinx

demosys/effects/effect.py

@@ -16,7 +16,7 @@ def bind_target(func):
     """
     Decorator auto binding and releasing the incoming FBO in ``draw()``.
 
-    literal blocks::
+    example::
 
        @bind_target
         def draw(...):

demosys/opengl/fbo.py

@@ -31,7 +31,13 @@ def mglo(cls):
 
 
 class FBO:
-    """Frame buffer object"""
+    """
+    A framebuffer object is a collection of buffers that can be used as the destination for rendering.
+    The buffers for framebuffer objects reference images from either textures.
+
+    A typical FBO has one or multiple color layers and a depth. Shaders can write to these buffers
+    when activated.
+    """
     _stack = []
 
     def __init__(self):
@@ -47,7 +53,7 @@ def create_from_textures(color_buffers: List[Texture2D], depth_buffer: DepthText
         :param color_buffers: List of textures
         :param depth_buffer: Depth texture
 
-        :return: FBO instance
+        :return: A new :py:class:`FBO`
         """
         instance = FBO()
         instance.color_buffers = color_buffers
@@ -70,8 +76,7 @@ def create(size, components=4, depth=False, dtype='f1', layers=1) -> 'FBO':
         :param depth: (bool) Create a depth attachment
         :param dtype: (string) data type per r, g, b, a ...
         :param layers: (int) number of color attachments
-
-        :return: A new FBO
+        :return: A new :py:class:`FBO`
         """
         instance = FBO()
 
@@ -150,6 +155,12 @@ def __exit__(self, exc_type, exc_val, exc_tb):
     def use(self, stack=True):
         """
         Bind FBO adding it to the stack.
+        Optionally a context manager can be used:
+
+        optonally a context manager can be used::
+
+            with fbo:
+                # draw stuff
 
         :param stack: (bool) If the bind should push the current FBO on the stack.
         """

demosys/opengl/texture/__init__.py

@@ -1,3 +1,3 @@
-from .texture import Texture2D
-from .array import TextureArray
-from .depth import DepthTexture
+from .texture import Texture2D  # noqa
+from .array import TextureArray  # noqa
+from .depth import DepthTexture  # noqa

demosys/opengl/texture/array.py

@@ -6,7 +6,13 @@
 
 
 class TextureArray(BaseTexture):
-    """This is the class docstring"""
+    """
+    A TextureArray is a texture where each mipmap level contains an array of
+    images of the same size. Array textures may have Mipmaps, but each mipmap
+    in the texture has the same number of levels.
+
+    The image data size must exactly match (width, height * layers)
+    """
 
     def __init__(self, path: str=None, mipmap: bool=False, layers=0, **kwargs) -> 'TextureArray':
         """
@@ -35,6 +41,7 @@ def create(cls, size, components=4, data=None, alignment=1, dtype='f1', mipmap=F
         :param alignment: The byte alignment 1, 2, 4 or 8
         :param dtype: (str) The data type
         :param mipmap: (bool) Generate mipmaps
+        :returns: :py:class:`TextureArray` object
         """
         texture = TextureArray("create", mipmap=False, layers=size[2])
         texture.mglo = context.ctx().texture_array(
@@ -50,6 +57,7 @@ def create(cls, size, components=4, data=None, alignment=1, dtype='f1', mipmap=F
     def set_image(self, image, flip=True):
         """
         Set pixel data using a image file with PIL/Pillow.
+        The image size must exactly match (width, height * layers)
 
         :param image: The PIL/Pillow image object
         :param flip: Flip the image top to bottom

demosys/opengl/texture/base.py

@@ -14,7 +14,7 @@ def __init__(self):
 
     def use(self, location=0):
         """
-        Bind the texture.
+        Bind the texture to a channel/location.
 
         :param location: The texture location. (GL_TEXTURE0 + location)
         """

demosys/opengl/texture/depth.py

@@ -5,14 +5,17 @@
 
 
 class DepthTexture(BaseTexture):
-    """Depth Texture"""
+    """
+    A DepthTexture is a texture for storing depth information during rendering.
+    They are attachments to :py:class:`demosys.opengl.FBO`.
+    """
 
     # Class attributes for drawing the texture
     quad = None
     shader = None
     sampler = None
 
-    def __init__(self, size, data=None, samples=0, alignment=8):
+    def __init__(self, size, data=None, samples=0, alignment=4):
         """
         Create a depth texture
 
@@ -27,12 +30,24 @@ def __init__(self, size, data=None, samples=0, alignment=8):
         _init_depth_texture_draw()
 
     @classmethod
-    def create(cls, size, data=None, samples=0, alignment=8) -> 'DepthTexture':
+    def create(cls, size, data=None, samples=0, alignment=4) -> 'DepthTexture':
+        """
+        Creates a :py:class:`DepthTexture` object
+
+        :param size: (tuple) The width and height of the texture.
+        :param data: (bytes) Content of the texture.
+        :param samples: The number of samples. Value 0 means no multisample format.
+        :param alignment: The byte alignment 1, 2, 4 or 8.
+        :return: :py:class:`DepthTexture` object
+        """
         return cls(size, data=data, samples=samples, alignment=alignment)
 
     def draw(self, near, far, pos=(0.0, 0.0), scale=(1.0, 1.0)):
         """
         Draw depth buffer linearized.
+        By default this will draw the texture as a full screen quad.
+        A sampler will be used to ensure the right conditions to draw the depth buffer.
+
         :param near: Near plane in projection
         :param far: Far plane in projection
         :param pos: (tuple) offset x, y

demosys/opengl/texture/texture.py

@@ -7,7 +7,12 @@
 
 
 class Texture2D(BaseTexture):
-    """2D Texture"""
+    """
+    A Texture is an OpenGL object that contains one or more images that all
+    have the same image format. A texture can be used in two ways. It can
+    be the source of a texture access from a Shader, or it can be used
+    as a render target.
+    """
 
     # Class attributes for drawing the texture
     quad = None
@@ -43,7 +48,7 @@ def create(cls, size, components=4, data=None, samples=0, alignment=1, dtype='f1
         :param alignment: Data alignment (1, 2, 4 or 8)
         :param dtype: Datatype for each component
         :param mipmap: Generate mipmaps
-        :return: Texture object
+        :return: :py:class:`Texture2D` object
         """
         texture = Texture2D(path="dynamic", mipmap=mipmap)
 
@@ -69,7 +74,7 @@ def from_image(cls, path, image=None, **kwargs):
 
         :param path: The path to the file
         :param image: The PIL/Pillow image object (Can be None)
-        :return: Texture object
+        :return: :py:class:`Texture2D` object
         """
         texture = Texture2D(path=path, **kwargs)
         if image:
@@ -97,7 +102,8 @@ def set_image(self, image, flip=True):
 
     def draw(self, pos=(0.0, 0.0), scale=(1.0, 1.0)):
         """
-        Draw texture
+        Draw texture using a fullscreen quad.
+        By default this will conver the entire screen.
 
         :param pos: (tuple) offset x, y
         :param scale: (tuple) scale x, y

demosys/scene/loaders/wavefront.py

@@ -5,7 +5,6 @@
 from pywavefront import cache
 from pywavefront.obj import ObjParser
 
-from demosys import context
 from demosys.opengl import VAO
 from demosys.resources import textures
 from demosys.scene import Material, MaterialTexture, Mesh, Node

demosys/scene/scene.py

@@ -33,7 +33,7 @@ def __init__(self, name, loader=None, mesh_shaders=None, **kwargs):
         self.bbox_vao = geometry.bbox()
         self.bbox_shader = shaders.get('scene_default/bbox.glsl', create=True)
 
-        self._view_matrix = matrix44.create_identity()        
+        self._view_matrix = matrix44.create_identity()
 
     @property
     def view_matrix(self):