Code documentation

Started documenting code, and rewording some existing documentation.

README.rst

@@ -10,7 +10,7 @@ pyeasyga
 
 -------------------------------------------------------------------
 
-A simple and easy-to-use Genetic Algorithm implementation in Python
+A simple and easy-to-use Genetic Algorithm implementation library in Python.
 
 ``pyeasyga`` provides a simple interface to the power of Genetic Algorithms
 (GAs). You don't have to have expert GA knowledge in order to use it.

docs/conf.py

@@ -270,7 +270,7 @@
      u'pyeasyga Documentation',
      u'Ayodeji Remi-Omosowon',
      'pyeasyga',
-     'A simple and easy-to-use Genetic Algorithm implementation in Python.',
+     'A simple and easy-to-use Genetic Algorithm implementation library in Python.',
      'Optimisation algorithms'),
 ]
 

docs/index.rst

@@ -1,12 +1,11 @@
-.. complexity documentation master file, created by
-   sphinx-quickstart on Tue Jul  9 22:26:36 2013.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
+.. documentation master file, created by sphinx-quickstart on 
+   Tue Jul  9 22:26:36 2013. You can adapt this file completely to your liking,
+   but it should at least contain the root `toctree` directive.
 
 pyeasyga
 ==================================================
 
-*A simple and easy-to-use Genetic Algorithm implementation in Python*
+*A simple and easy-to-use Genetic Algorithm implementation library in Python*
 
 **Contents:**
 

pyeasyga/__init__.py

@@ -1,4 +1,15 @@
 # -*- coding: utf-8 -*-
+"""pyeasyga
+
+A simple and easy-to-use genetic algorithm implementation library in Python.
+
+For a bit array solution representation, simply instantiate the
+GeneticAlgorithm class with input data, define and supply a fitness function,
+run the Genetic Algorithm, and retrieve the solution!
+
+Other solution representations will require setting some more attributes.
+
+"""
 
 __author__ = 'Ayodeji Remi-Omosowon'
 __email__ = 'remiomosowon@gmail.com'

pyeasyga/pyeasyga.py

@@ -1,16 +1,52 @@
 # -*- coding: utf-8 -*-
+"""
+    pyeasyga module
+
+"""
+
 import random
 import copy
 from operator import attrgetter
 
 
 class GeneticAlgorithm(object):
+    """ Genetic Algorithm class.
+
+    This is the main class that controls the functionality of the Genetic
+    Algorithm.
+
+    >>> # Select only two items from the list and maximise profit
+    >>> from pyeasyga.pyeasyga import GeneticAlgorithm
+    >>> input_data = [('pear', 50), ('apple', 35), ('banana', 40)]
+    >>> easyga = GeneticAlgorithm(input_data)
+    >>> def fitness (member, data):
+    >>>     return sum([profit for (selected, (fruit, profit)) in
+    >>>                 zip(member, data) if selected and
+    >>>                 member.count(1) == 2])
+    >>> easyga.fitness_function = fitness
+    >>> easyga.run()
+    >>> print easyga.best_individual()
+
+    """
+
     def __init__(self,
                  seed_data,
                  population_size=100,
                  generations=300,
                  crossover_probability=0.8,
                  mutation_probability=0.2):
+        """ Instantiate the Genetic Algorithm.
+
+        :param seed_data: input data to the Genetic Algorithm
+        :type seed_data: list of objects
+        :param int population_size: size of population
+        :param int generations: number of generations to evolve
+        :param float crossover_probability: probability of crossover operation
+        :param float mutation_probability: probability of mutation operation
+        :returns: None
+
+        """
+
         self.seed_data = seed_data
         self.population_size = population_size
         self.generations = generations
@@ -22,9 +58,27 @@ def __init__(self,
         self.maximise_fitness = True
 
         def create_individual(seed_data):
+            """ Create a candidate solution representation.
+
+            e.g. for a bit array representation:
+
+            >>> return [random.randint(0, 1) for _ in xrange(len(data))]
+
+            :param seed_data: input data to the Genetic Algorithm
+            :type seed_data: list of objects
+            :returns: candidate solution representation as a list
+
+            """
             return [random.randint(0, 1) for _ in xrange(len(seed_data))]
 
         def crossover(parent_1, parent_2):
+            """ Crossover (mate) two parents to produce two children
+
+            :param parent_1: candidate solution representation (list)
+            :param parent_2: candidate solution representation (list)
+            :returns: tuple containing two children
+
+            """
             index = random.randrange(1, len(parent_1))
             child_1 = parent_1[:index] + parent_2[index:]
             child_2 = parent_2[:index] + parent_1[index:]

setup.py

@@ -37,7 +37,7 @@ def find_version(*file_paths):
 setup(
     name='pyeasyga',
     version=find_version('pyeasyga', '__init__.py'),
-    description='A simple and easy-to-use Genetic Algorithm implementation in Python',
+    description='A simple and easy-to-use Genetic Algorithm implementation library in Python',
     long_description=readme + '\n\n' + history,
     author='Ayodeji Remi-Omosowon',
     author_email='remiomosowon@gmail.com',

tests/test_pyeasyga.py

@@ -43,7 +43,7 @@ def setUp(self):
         self.ga.fitness_function = lambda member, data: sum(
             [profit for (selected, (fruit, profit)) in
              zip(member, data) if selected and
-             len([x for x in member if x == 1]) == 3])
+             member.count(1) == 3])
 
         def mutate(individual):
             mutate_index = random.randrange(len(individual))
@@ -174,7 +174,7 @@ def test_selection_function_2(self):
 
     def test_selection_function_3(self):
         ''' Test random selection '''
-        self.ga.selection_function = self.ga.random_selection 
+        self.ga.selection_function = self.ga.random_selection
         individual = self.ga.selection_function(self.population)
 
         assert len(individual) == 5