redistribute the module level docstrings

src/mdptoolbox/__init__.py

 # -*- coding: utf-8 -*-
+"""Markov Decision Process (MDP) Toolbox
+=====================================
 
-import mdp
\ No newline at end of file
+The MDP toolbox provides classes and functions for the resolution of
+descrete-time Markov Decision Processes.
+
+Available modules
+-----------------
+example
+    Examples of transition and reward matrices that form valid MDPs
+mdp
+    Makov decision process algorithms
+utils
+    Functions for validating and working with an MDP
+
+How to use the documentation
+----------------------------
+Documentation is available both as docstrings provided with the code and
+in html or pdf format from 
+`The MDP toolbox homepage <http://www.somewhere.com>`_. The docstring
+examples assume that the ``mdptoolbox`` package is imported like so::
+
+  >>> import mdptoolbox
+
+To use the built-in examples, then the ``example`` module must be imported::
+
+  >>> import mdptoolbox.example
+
+Once the ``example`` module has been imported, then it is no longer neccesary
+to issue ``import mdptoolbox``.
+
+Code snippets are indicated by three greater-than signs::
+
+  >>> x = 17
+  >>> x = x + 1
+  >>> x
+  18
+
+The documentation can be displayed with
+`IPython <http://ipython.scipy.org>`_. For example, to view the docstring of
+the ValueIteration class use ``mdp.ValueIteration?<ENTER>``, and to view its
+source code use ``mdp.ValueIteration??<ENTER>``.
+
+Acknowledgments
+---------------
+This module is modified from the MDPtoolbox (c) 2009 INRA available at 
+http://www.inra.fr/mia/T/MDPtoolbox/.
+
+"""
+
+# Copyright (c) 2011-2013 Steven A. W. Cordwell
+# Copyright (c) 2009 INRA
+# 
+# All rights reserved.
+# 
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+# 
+#   * Redistributions of source code must retain the above copyright notice,
+#     this list of conditions and the following disclaimer.
+#   * Redistributions in binary form must reproduce the above copyright notice,
+#     this list of conditions and the following disclaimer in the documentation
+#     and/or other materials provided with the distribution.
+#   * Neither the name of the <ORGANIZATION> nor the names of its contributors
+#     may be used to endorse or promote products derived from this software
+#     without specific prior written permission.
+# 
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+
+import mdp
+
+if __name__ == "__main__":
+    import doctest
+    doctest.testfile("example.py", module_relative=True)
+    doctest.testfile("mdp.py", module_relative=True)
+    doctest.testfile("utils.py", module_relative=True)

src/mdptoolbox/example.py

 # -*- coding: utf-8 -*-
-"""
-Created on Sun Aug 18 14:32:25 2013
+"""Markov Decision Process (MDP) Toolbox: ``example`` module
+=========================================================
+
+The ``example`` module provides functions to generate valid MDP transition and
+reward matrices that are valid.
+
+Available functions
+-------------------
+forest
+    A simple forest management example
+rand
+    A random example
 
-@author: steve
 """
 
+# Copyright (c) 2011-2013 Steven A. W. Cordwell
+# Copyright (c) 2009 INRA
+# 
+# All rights reserved.
+# 
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+# 
+#   * Redistributions of source code must retain the above copyright notice,
+#     this list of conditions and the following disclaimer.
+#   * Redistributions in binary form must reproduce the above copyright notice,
+#     this list of conditions and the following disclaimer in the documentation
+#     and/or other materials provided with the distribution.
+#   * Neither the name of the <ORGANIZATION> nor the names of its contributors
+#     may be used to endorse or promote products derived from this software
+#     without specific prior written permission.
+# 
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+
 from numpy import diag, ones, where, zeros
 from numpy.random import randint, random
 from scipy.sparse import coo_matrix, dok_matrix
@@ -241,3 +279,7 @@ def rand(S, A, is_sparse=False, mask=None):
                 R[a][s] = (m * (2*random(S) - ones(S, dtype=int)))
     # we want to return the generated transition and reward matrices
     return (P, R)
+
+if __name__ == "__main__":
+    import doctest
+    doctest.testmod()

src/mdptoolbox/mdp.py

 # -*- coding: utf-8 -*-
-"""Markov Decision Process (MDP) Toolbox
-=====================================
+"""Markov Decision Process (MDP) Toolbox: ``mdp`` module
+=====================================================
 
-The MDP toolbox provides classes and functions for the resolution of
-descrete-time Markov Decision Processes.
+The ``mdp`` module provides classes for the resolution of descrete-time Markov
+Decision Processes.
 
 Available classes
 -----------------
@@ -26,43 +26,6 @@ ValueIteration
 ValueIterationGS
     Gauss-Seidel value iteration MDP
 
-Available functions
--------------------
-check
-    Check that an MDP is properly defined
-checkSquareStochastic
-    Check that a matrix is square and stochastic
-exampleForest
-    A simple forest management example
-exampleRand
-    A random example
-
-How to use the documentation
-----------------------------
-Documentation is available both as docstrings provided with the code and
-in html or pdf format from 
-`The MDP toolbox homepage <http://www.somewhere.com>`_. The docstring
-examples assume that the `mdp` module has been imported imported like so::
-
-  >>> import mdptoolbox.mdp as mdp
-
-Code snippets are indicated by three greater-than signs::
-
-  >>> x = 17
-  >>> x = x + 1
-  >>> x
-  18
-
-The documentation can be displayed with
-`IPython <http://ipython.scipy.org>`_. For example, to view the docstring of
-the ValueIteration class use ``mdp.ValueIteration?<ENTER>``, and to view its
-source code use ``mdp.ValueIteration??<ENTER>``.
-
-Acknowledgments
----------------
-This module is modified from the MDPtoolbox (c) 2009 INRA available at 
-http://www.inra.fr/mia/T/MDPtoolbox/.
-
 """
 
 # Copyright (c) 2011-2013 Steven A. W. Cordwell

src/mdptoolbox/utils.py

 # -*- coding: utf-8 -*-
-"""
-Created on Sun Aug 18 14:30:09 2013
+"""Markov Decision Process (MDP) Toolbox: ``utils`` module
+=======================================================
+
+The ``utils`` module provides functions to check that an MDP is validly
+described. There are also functions for working with MDPs while they are being
+solved.
+
+Available functions
+-------------------
+check
+    Check that an MDP is properly defined
+checkSquareStochastic
+    Check that a matrix is square and stochastic
+getSpan
+    Calculate the span of an array
 
-@author: steve
 """
 
+# Copyright (c) 2011-2013 Steven A. W. Cordwell
+# Copyright (c) 2009 INRA
+# 
+# All rights reserved.
+# 
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+# 
+#   * Redistributions of source code must retain the above copyright notice,
+#     this list of conditions and the following disclaimer.
+#   * Redistributions in binary form must reproduce the above copyright notice,
+#     this list of conditions and the following disclaimer in the documentation
+#     and/or other materials provided with the distribution.
+#   * Neither the name of the <ORGANIZATION> nor the names of its contributors
+#     may be used to endorse or promote products derived from this software
+#     without specific prior written permission.
+# 
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+
 from numpy import absolute, ones
 
 SMALLNUM = 10e-12
@@ -294,3 +335,7 @@ class InvalidMDPError(Error):
         Error.__init__(self)
         self.message += msg
         self.args = tuple(msg)
+
+if __name__ == "__main__":
+    import doctest
+    doctest.testmod()