Major api doc cleanup

Author: einarf

demosys/core/finders.py

@@ -14,9 +14,22 @@ def __init__(self, paths):
         self._cache = {}
 
     def find(self, path):
+        """
+        Find a file in the path.
+        When creating a custom finder, this is the method you override.
+
+        :param path: The path to find
+        :return: The absolute path to the file or None if not found
+        """
         return self._find(path)
 
     def _find(self, path):
+        """
+        Similar to ``find()``, but it caches each result to speed things.
+
+        :param path: The path to find
+        :return: The absolute path to the file or None if not found
+        """
         for p in self.paths:
             abspath = os.path.join(p, path)
             if os.path.exists(abspath):
@@ -28,10 +41,25 @@ def _find(self, path):
         return None
 
     def find_cached(self, path):
+        """
+        Check if the path is already cached.
+        This method should normally not be overridden.
+
+        :param path: The path to the file
+        :return: The absolute path to the file or None
+        """
         e = self._cache.get(path)
         if e.exists:
             return e.abspath
         return None
 
     def cache(self, path, abspath, exists=True):
+        """
+        Caches an entry.
+        Should ideally not be overridden.
+
+        :param path: The path
+        :param abspath: The absolute path
+        :param exists: Did the file exist? (bool)
+        """
         self._cache[path] = FinderEntry(path=path, abspath=abspath, exists=exists)

demosys/core/management/base.py

@@ -14,25 +14,53 @@ def __init__(self):
         pass
 
     def add_arguments(self, parser):
+        """
+        This method is for adding arguments to a command.
+        When extending this class we define the arguments
+        by adding it to the parser passed in.
+
+        :param parser: The parser to add arguments to (standard argparse)
+        """
         pass
 
     def handle(self, *args, **options):
+        """
+        The actual run logic for the command.
+
+        :param args: arguments from the argparser
+        :param options: keyword arguments from the argparser
+        """
         raise NotImplementedError
 
     def run_from_argv(self, argv):
+        """
+        Called by the system when executing the command from the command line.
+        This should not be overridden.
+
+        :param argv: Arguments from command line
+        """
         parser = self.create_parser(argv[0], argv[1])
         options = parser.parse_args(argv[2:])
         cmd_options = vars(options)
         args = cmd_options.pop('args', ())
         self.handle(*args, **cmd_options)
 
     def print_help(self, prog_name, subcommand):
+        """
+        Prints the help text generated by the argument parser defined for this command.
+        This method should not be overridden.
+
+        :param prog_name: name of the program that started the command.
+        :param subcommand: The subcommand name
+        """
         parser = self.create_parser(prog_name, subcommand)
         parser.print_help()
 
     def create_parser(self, prog_name, subcommand):
         """
         Create argument parser and deal with ``add_arguments``.
+        This method should not be overriden.
+
         :param prog_name: Name of the command (argv[0])
         :return: ArgumentParser
         """
@@ -46,7 +74,12 @@ class CreateCommand(BaseCommand):
     """Used for createproject and createeffect"""
 
     def validate_name(self, name):
-        """Can the name be used as a python module or package?"""
+        """
+        Can the name be used as a python module or package?
+        Raises ``ValueError`` if the name is invalid.
+
+        :param name: the name to check
+        """
         if not name:
             raise ValueError("Name cannot be empty")
 
@@ -55,10 +88,15 @@ def validate_name(self, name):
             raise ValueError("{} is not a valid identifier".format(name))
 
     def try_import(self, name):
-        """Attemt to import the name"""
+        """
+        Attempt to import the name.
+        Raises ``ImportError`` if the name cannot be imported.
+
+        :param name: the name to import
+        """
         try:
             import_module(name)
         except ImportError:
             pass
         else:
-            raise ValueError("{} conflicts with an existing python module".format(name))
+            raise ImportError("{} conflicts with an existing python module".format(name))

demosys/core/shaderfiles/finders.py

@@ -18,10 +18,6 @@ def __init__(self):
             )
         super().__init__(settings.SHADER_DIRS)
 
-    # TODO: Use values from settings to filter shader files
-    # def find(self, path):
-    #     pass
-
 
 class EffectDirectoriesFinder(finders.FileSystemFinder):
     """Finds shaders in the registered effects"""
@@ -42,6 +38,14 @@ def get_finders():
 
 @functools.lru_cache(maxsize=None)
 def get_finder(import_path):
+    """
+    Get a finder class from an import path.
+    Raises ``demosys.core.exceptions.ImproperlyConfigured`` if the finder is not found.
+    This function uses an lru cache.
+
+    :param import_path: string representing an import path
+    :return: An instance of the finder
+    """
     Finder = import_string(import_path)
     if not issubclass(Finder, finders.FileSystemFinder):
         raise ImproperlyConfigured('Finder {} is not a subclass of core.finders.FileSystemFinder'.format(import_path))

demosys/core/texturefiles/finders.py

@@ -42,6 +42,14 @@ def get_finders():
 
 @functools.lru_cache(maxsize=None)
 def get_finder(import_path):
+    """
+    Get a finder class from an import path.
+    Raises ``demosys.core.exceptions.ImproperlyConfigured`` if the finder is not found.
+    This function uses an lru cache.
+
+    :param import_path: string representing an import path
+    :return: An instance of the finder
+    """
     Finder = import_string(import_path)
     if not issubclass(Finder, finders.FileSystemFinder):
         raise ImproperlyConfigured('Finder {} is not a subclass of core.finders.FileSystemFinder'.format(import_path))

demosys/effects/default/effect.py

@@ -5,7 +5,7 @@
 
 
 class DefaultEffect(effect.Effect):
-    """Generated default efffect"""
+    """Generated default effect"""
     def __init__(self):
         self.shader = self.get_shader("default/default.glsl")
         self.cube = geometry.cube(4.0, 4.0, 4.0)

demosys/effects/managers.py

@@ -6,27 +6,52 @@ class ManagerError(Exception):
 
 
 class BaseEffectManger:
-    """Base effect manager"""
+    """
+    Base effect manager.
+    A manager is responsible for figuring out what effect should be drawn
+    at any given time.
+    """
     def pre_load(self):
-        """Init after context creations"""
+        """
+        Called after OpenGL context creation before resources are loaded.
+        This method should be overridden.
+        """
         return True
 
     def post_load(self):
+        """
+        Called after resources are loaded.
+        This method should be overridden.
+        """
         return True
 
     def draw(self, time, frametime, target):
-        """Draw efffect(s)"""
+        """
+        Called by the system every frame.
+        This method should be overridden.
+
+        :param time: The current time in seconds
+        :param frametime: The time one frame should take in seconds
+        :param target: The target FBO
+        """
         pass
 
 
 class SingleEffectManager(BaseEffectManger):
     """Run a single effect"""
     def __init__(self, effect_module=None):
+        """
+        Initalize the manager telling it what effect should run.
+
+        :param effect_module: The effect module to run
+        """
         self.active_effect = None
         self.effect_module = effect_module
 
     def pre_load(self):
-        """Init after context creations"""
+        """
+        Initialize the effect that should run.
+        """
         effect_list = [cfg.cls() for name, cfg in effects.effects.items()]
         for effect in effect_list:
             if effect.name == self.effect_module:

demosys/effects/registry.py

@@ -28,12 +28,18 @@ def __init__(self):
         self.effects = {}
 
     def get_dirs(self):
-        """Get all effect directories"""
+        """
+        Get all effect directories for registered effects.
+        """
         for k, v in self.effects.items():
             yield v.path
 
     def polulate(self, effect_list):
-        """Find all effects"""
+        """
+        Find all effect modules.
+
+        :param effect_list: List of effect module paths
+        """
         for effect in effect_list:
             name = '{}.{}'.format(effect, EFFECT_MODULE)
             module, cls = self.get_effect_cls(name)
@@ -44,7 +50,9 @@ def polulate(self, effect_list):
                 raise EffectError("Effect '{}' has no effect class".format(effect))
 
     def get_effect_cls(self, module_name):
-        """Find and return an effect class in a module
+        """
+        Find and return an effect class in a module
+
         :param module_name: Name of the module
         :returns: module, cls tuple
         """