Clean up docstrings so the Sphinx build is warning-free (#666)

Reformat the docstrings flagged by the Sphinx (autodoc) build so they parse as
valid reStructuredText, without changing any wording or code: indented class
hierarchies, attribute/argument lists, usage examples and equations are now
proper literal blocks (`::` + surrounding blank lines), enumerated/bulleted
lists get the required blank line, and stray inline markup (unbalanced
backticks, `*args`, `P(e|s)` pipes) is escaped, switching the affected
docstrings to raw strings where needed. Covers agents, agents4e, csp, planning,
logic, logic4e, learning, learning4e, reinforcement_learning(4e), utils, utils4e,
games, games4e, mdp, mdp4e, probability, probability4e, perception4e,
deep_learning4e, knowledge, probabilistic_learning, search and text. The docs
now build with 0 warnings (was 126); all module imports and test suites are
unaffected.

Author: dmeoli

agents.py

@@ -1,29 +1,30 @@
 """
 Implement Agents and Environments. (Chapters 1-2)
 
-The class hierarchies are as follows:
+The class hierarchies are as follows::
 
-Thing ## A physical object that can exist in an environment
-    Agent
-        Wumpus
-    Dirt
-    Wall
-    ...
+    Thing  ## A physical object that can exist in an environment
+        Agent
+            Wumpus
+        Dirt
+        Wall
+        ...
+
+    Environment  ## An environment holds objects, runs simulations
+        XYEnvironment
+            VacuumEnvironment
+            WumpusEnvironment
 
-Environment ## An environment holds objects, runs simulations
-    XYEnvironment
-        VacuumEnvironment
-        WumpusEnvironment
+An agent program is a callable instance, taking percepts and choosing actions::
 
-An agent program is a callable instance, taking percepts and choosing actions
     SimpleReflexAgentProgram
     ...
 
-EnvGUI ## A window with a graphical representation of the Environment
+The GUI helpers are::
 
-EnvToolbar ## contains buttons for controlling EnvGUI
-
-EnvCanvas ## Canvas to display the environment of an EnvGUI
+    EnvGUI      ## A window with a graphical representation of the Environment
+    EnvToolbar  ## contains buttons for controlling EnvGUI
+    EnvCanvas   ## Canvas to display the environment of an EnvGUI
 """
 
 # TODO
@@ -284,10 +285,12 @@ def program(percept):
 
 class Environment:
     """Abstract class representing an Environment. 'Real' Environment classes
-    inherit from this. Your Environment will typically need to implement:
-        percept:           Define the percept that an agent sees.
-        execute_action:    Define the effects of executing an action.
-                           Also update the agent.performance slot.
+    inherit from this. Your Environment will typically need to implement::
+
+        percept:         Define the percept that an agent sees.
+        execute_action:  Define the effects of executing an action;
+                         also update the agent.performance slot.
+
     The environment keeps a list of .things and .agents (which is a subset
     of .things). Each agent has a .performance slot, initialized to 0.
     Each thing has a .location slot, even though some environments may not
@@ -385,13 +388,16 @@ def delete_thing(self, thing):
 
 
 class Direction:
-    """A direction class for agents that want to move in a 2D plane
-        Usage:
-            d = Direction("down")
-            To change directions:
-            d = d + "right" or d = d + Direction.R #Both do the same thing
-            Note that the argument to __add__ must be a string and not a Direction object.
-            Also, it (the argument) can only be right or left."""
+    """A direction class for agents that want to move in a 2D plane.
+
+    Usage::
+
+        d = Direction("down")
+        # to change directions:
+        d = d + "right" or d = d + Direction.R  # both do the same thing
+
+    Note that the argument to __add__ must be a string and not a Direction
+    object, and it can only be 'right' or 'left'."""
 
     R = "right"
     L = "left"

agents4e.py

@@ -1,21 +1,22 @@
 """
 Implement Agents and Environments. (Chapters 1-2)
 
-The class hierarchies are as follows:
+The class hierarchies are as follows::
 
-Thing ## A physical object that can exist in an environment
-    Agent
-        Wumpus
-    Dirt
-    Wall
-    ...
+    Thing ## A physical object that can exist in an environment
+        Agent
+            Wumpus
+        Dirt
+        Wall
+        ...
+
+    Environment ## An environment holds objects, runs simulations
+        XYEnvironment
+            VacuumEnvironment
+            WumpusEnvironment
 
-Environment ## An environment holds objects, runs simulations
-    XYEnvironment
-        VacuumEnvironment
-        WumpusEnvironment
+An agent program is a callable instance, taking percepts and choosing actions::
 
-An agent program is a callable instance, taking percepts and choosing actions
     SimpleReflexAgentProgram
     ...
 
@@ -289,10 +290,12 @@ def program(percept):
 
 class Environment:
     """Abstract class representing an Environment. 'Real' Environment classes
-    inherit from this. Your Environment will typically need to implement:
+    inherit from this. Your Environment will typically need to implement::
+
         percept:           Define the percept that an agent sees.
         execute_action:    Define the effects of executing an action.
                            Also update the agent.performance slot.
+
     The environment keeps a list of .things and .agents (which is a subset
     of .things). Each agent has a .performance slot, initialized to 0.
     Each thing has a .location slot, even though some environments may not
@@ -391,12 +394,15 @@ def delete_thing(self, thing):
 
 class Direction:
     """A direction class for agents that want to move in a 2D plane
-        Usage:
-            d = Direction("down")
-            To change directions:
-            d = d + "right" or d = d + Direction.R #Both do the same thing
-            Note that the argument to __add__ must be a string and not a Direction object.
-            Also, it (the argument) can only be right or left."""
+
+    Usage::
+
+        d = Direction("down")
+        To change directions:
+        d = d + "right" or d = d + Direction.R #Both do the same thing
+        Note that the argument to __add__ must be a string and not a Direction object.
+        Also, it (the argument) can only be right or left.
+    """
 
     R = "right"
     L = "left"

csp.py

@@ -16,7 +16,8 @@
 
 class CSP(search.Problem):
     """This class describes finite-domain Constraint Satisfaction Problems.
-    A CSP is specified by the following inputs:
+    A CSP is specified by the following inputs::
+
         variables   A list of variables; each is atomic (e.g. int or string).
         domains     A dict of {var:[possible_value, ...]} entries.
         neighbors   A dict of {var:[var,...]} that for each variable lists
@@ -35,18 +36,23 @@ class CSP(search.Problem):
     However, the class also supports data structures and methods that help you
     solve CSPs by calling a search function on the CSP. Methods and slots are
     as follows, where the argument 'a' represents an assignment, which is a
-    dict of {var:val} entries:
+    dict of {var:val} entries::
+
         assign(var, val, a)     Assign a[var] = val; do other bookkeeping
         unassign(var, a)        Do del a[var], plus other bookkeeping
         nconflicts(var, val, a) Return the number of other variables that
                                 conflict with var=val
         curr_domains[var]       Slot: remaining consistent values for var
                                 Used by constraint propagation routines.
-    The following methods are used only by graph_search and tree_search:
+
+    The following methods are used only by graph_search and tree_search::
+
         actions(state)          Return a list of actions
         result(state, action)   Return a successor of state
         goal_test(state)        Return true if all constraints satisfied
-    The following are just for debugging purposes:
+
+    The following are just for debugging purposes::
+
         nassigns                Slot: tracks the number of assignments made
         display(a)              Print a human-readable representation
     """
@@ -656,17 +662,20 @@ class NQueensCSP(CSP):
     Suitable for large n, it uses only data structures of size O(n).
     Think of placing queens one per column, from left to right.
     That means position (x, y) represents (var, val) in the CSP.
-    The main structures are three arrays to count queens that could conflict:
+    The main structures are three arrays to count queens that could conflict::
+
         rows[i]      Number of queens in the ith row (i.e. val == i)
         downs[i]     Number of queens in the \ diagonal
                      such that their (x, y) coordinates sum to i
         ups[i]       Number of queens in the / diagonal
                      such that their (x, y) coordinates have x-y+n-1 = i
+
     We increment/decrement these counts each time a queen is placed/moved from
     a row/diagonal. So moving is O(1), as is nconflicts.  But choosing
     a variable, and a best value for the variable, are each O(n).
     If you want, you can keep track of conflicted variables, then variable
     selection will also be O(1).
+
     >>> len(backtracking_search(NQueensCSP(8)))
     8
     """
@@ -947,8 +956,9 @@ def display(self, assignment=None):
 
     def consistent(self, assignment):
         """assignment is a variable:value dictionary
+
         returns True if all of the constraints that can be evaluated
-                        evaluate to True given assignment.
+        evaluate to True given assignment.
         """
         return all(con.holds(assignment)
                    for con in self.constraints

deep_learning4e.py

@@ -526,9 +526,11 @@ def keras_dataset_loader(dataset, max_length=500):
 def SimpleRNNLearner(train_data, val_data, epochs=2, verbose=False):
     """
     RNN example for text sentimental analysis.
-    :param train_data: a tuple of (training data, targets)
-            Training data: ndarray taking training examples, while each example is coded by embedding
-            Targets: ndarray taking targets of each example. Each target is mapped to an integer
+
+    :param train_data:
+        a tuple of (training data, targets)
+        Training data: ndarray taking training examples, while each example is coded by embedding
+        Targets: ndarray taking targets of each example. Each target is mapped to an integer
     :param val_data: a tuple of (validation data, targets)
     :param epochs: number of epochs
     :param verbose: verbosity mode

games.py

@@ -50,8 +50,8 @@ def expect_minmax(state, game):
     """
     [Figure 5.11]
     Return the best move for a player after dice are thrown. The game tree
-	includes chance nodes along with min and max nodes.
-	"""
+    includes chance nodes along with min and max nodes.
+    """
     player = game.to_move(state)
 
     def max_value(state):
@@ -535,8 +535,8 @@ def checkers_at_home(self, board, player):
 
     def is_legal_move(self, board, start, steps, player):
         """Move is a tuple which contains starting points of checkers to be
-		moved during a player's turn. An on-board move is legal if both the destinations
-		are open. A bear-off move is the one where a checker is moved off-board.
+        moved during a player's turn. An on-board move is legal if both the destinations
+        are open. A bear-off move is the one where a checker is moved off-board.
         It is legal only after a player has moved all his checkers to his home."""
         dest1, dest2 = vector_add(start, steps)
         dest_range = range(0, 24)

games4e.py

@@ -50,8 +50,8 @@ def expect_minmax(state, game):
     """
     [Figure 5.11]
     Return the best move for a player after dice are thrown. The game tree
-	includes chance nodes along with min and max nodes.
-	"""
+    includes chance nodes along with min and max nodes.
+    """
     player = game.to_move(state)
 
     def max_value(state):
@@ -576,8 +576,8 @@ def checkers_at_home(self, board, player):
 
     def is_legal_move(self, board, start, steps, player):
         """Move is a tuple which contains starting points of checkers to be
-		moved during a player's turn. An on-board move is legal if both the destinations
-		are open. A bear-off move is the one where a checker is moved off-board.
+        moved during a player's turn. An on-board move is legal if both the destinations
+        are open. A bear-off move is the one where a checker is moved off-board.
         It is legal only after a player has moved all his checkers to his home."""
         dest1, dest2 = vector_add(start, steps)
         dest_range = range(0, 24)

knowledge.py

@@ -320,11 +320,12 @@ def choose_literal(self, literals, examples):
     def gain(self, l, examples):
         """
         Find the utility of each literal when added to the body of the clause. 
-        Utility function is: 
+        Utility function is::
+
             gain(R, l) = T * (log_2 (post_pos / (post_pos + post_neg)) - log_2 (pre_pos / (pre_pos + pre_neg)))
 
-        where: 
-        
+        where::
+
             pre_pos = number of positive bindings of rule R (=current set of rules)
             pre_neg = number of negative bindings of rule R 
             post_pos = number of positive bindings of rule R' (= R U {l} )