WIP: fix doc warnings

quantecon/cartesian.py

@@ -13,13 +13,13 @@
 def cartesian(nodes, order='C'):
     '''Cartesian product of a list of arrays
 
-    Parameters:
-    -----------
+    Parameters
+    ----------
     nodes: (list of 1d-arrays)
     order: ('C' or 'F') order in which the product is enumerated
 
-    Returns:
-    --------
+    Returns
+    -------
     out: (2d-array) each line corresponds to one point of the product space
     '''
 
@@ -50,15 +50,15 @@ def cartesian(nodes, order='C'):
 def mlinspace(a, b, nums, order='C'):
     '''Constructs a regular cartesian grid
 
-    Parameters:
-    -----------
+    Parameters
+    ----------
     a: (1d-array) lower bounds in each dimension
     b: (1d-array) upper bounds in each dimension
     nums: (1d-array) number of nodes along each dimension
     order: ('C' or 'F') order in which the product is enumerated
 
-    Returns:
-    --------
+    Returns
+    -------
     out: (2d-array) each line corresponds to one point of the product space
     '''
 

quantecon/compute_fp.py

@@ -86,9 +86,9 @@ def compute_fixed_point(T, v, error_tol=1e-3, max_iter=50, verbose=2,
     print_skip : scalar(int), optional(default=5)
         How many iterations to apply between print messages (effective
         only when `verbose=2`)
-    method : str in {'iteration', 'imitation_game'},
-             optional(default='iteration')
-        Method of computing an approximate fixed point
+    method : str, optional(default='iteration')
+        str in {'iteration', 'imitation_game'}. Method of computing
+        an approximate fixed point
     args, kwargs :
         Other arguments and keyword arguments that are passed directly
         to  the function T each time it is called

quantecon/game_theory/mclennan_tourky.py

@@ -25,8 +25,7 @@ def mclennan_tourky(g, init=None, epsilon=1e-3, max_iter=200,
     g : NormalFormGame
         NormalFormGame instance.
 
-    init : array_like(int or array_like(float, ndim=1)),
-           optional(default=None)
+    init : array_like(int or array_like(float, ndim=1)), optional
         Initial action profile, an array of N objects, where each object
         must be an iteger (pure action) or an array of floats (mixed
         action). If None, default to an array of zeros (the zero-th

quantecon/game_theory/normal_form_game.py

@@ -276,20 +276,20 @@ def best_response(self, opponents_actions, tie_breaking='smallest',
 
         Parameters
         ----------
-        opponents_actions : array_like(int or array_like(float)) or
-                            array_like(int, ndim=1) or scalar(int)
-            A profile of N-1 opponents' actions. If N=2, then it must be
-            a 1-dimensional array of floats (in which case it is treated
-            as the opponent's mixed action) or a scalar of integer (in
-            which case it is treated as the opponent's pure action). If
-            N>2, then it must be an array of N-1 objects, where each
-            object must be an integer (pure action) or an array of
-            floats (mixed action).
-
-        tie_breaking : {'smallest', 'random', False},
-                       optional(default='smallest')
-            Control how, or whether, to break a tie (see Returns for
-            details).
+        opponents_actions : scalar(int) or array_like
+            A profile of N-1 opponents' actions, represented by either
+            scalar(int), array_like(float), array_like(int), or
+            array_like(array_like(float)). If N=2, then it must be a
+            scalar of integer (in which case it is treated as the
+            opponent's pure action) or a 1-dimensional array of floats
+            (in which case it is treated as the opponent's mixed
+            action). If N>2, then it must be an array of N-1 objects,
+            where each object must be an integer (pure action) or an
+            array of floats (mixed action).
+
+        tie_breaking : str, optional(default='smallest')
+            str in {'smallest', 'random', False}. Control how, or 
+            whether, to break a tie (see Returns for details).
 
         payoff_perturbation : array_like(float), optional(default=None)
             Array of length equal to the number of actions of the player
@@ -300,8 +300,7 @@ def best_response(self, opponents_actions, tie_breaking='smallest',
             Tolerance level used in determining best responses. If None,
             default to the value of the `tol` attribute.
 
-        random_state : scalar(int) or np.random.RandomState,
-                       optional(default=None)
+        random_state : int or np.random.RandomState, optional
             Random seed (integer) or np.random.RandomState instance to
             set the initial state of the random number generator for
             reproducibility. If None, a randomly initialized RandomState
@@ -350,8 +349,7 @@ def random_choice(self, actions=None, random_state=None):
         actions : array_like(int), optional(default=None)
             An array of integers representing pure actions.
 
-        random_state : scalar(int) or np.random.RandomState,
-                       optional(default=None)
+        random_state : int or np.random.RandomState, optional
             Random seed (integer) or np.random.RandomState instance to
             set the initial state of the random number generator for
             reproducibility. If None, a randomly initialized RandomState
@@ -389,8 +387,7 @@ class NormalFormGame(object):
 
     Parameters
     ----------
-    data : array_like(Player) or array_like(int, ndim=1) or
-           array_like(float, ndim=2 or N+1)
+    data : array_like of Player, int (ndim=1), or float (ndim=2 or N+1)
         Data to initialize a NormalFormGame. `data` may be an array of
         Players, in which case the shapes of the Players' payoff arrays
         must be consistent. If `data` is an array of N integers, then
@@ -703,8 +700,8 @@ def best_response_2p(payoff_matrix, opponent_mixed_action, tol=1e-8):
     tol : scalar(float), optional(default=None)
         Tolerance level used in determining best responses.
 
-    Return
-    ------
+    Returns
+    -------
     scalar(int)
         Best response action.
 

quantecon/game_theory/random.py

@@ -22,8 +22,7 @@ def random_game(nums_actions, random_state=None):
     nums_actions : tuple(int)
         Tuple of the numbers of actions, one for each player.
 
-    random_state : scalar(int) or np.random.RandomState,
-                   optional(default=None)
+    random_state : int or np.random.RandomState, optional
         Random seed (integer) or np.random.RandomState instance to set
         the initial state of the random number generator for
         reproducibility. If None, a randomly initialized RandomState is
@@ -63,8 +62,7 @@ def covariance_game(nums_actions, rho, random_state=None):
         Covariance of a pair of payoff values. Must be in [-1/(N-1), 1],
         where N is the number of players.
 
-    random_state : scalar(int) or np.random.RandomState,
-                   optional(default=None)
+    random_state : int or np.random.RandomState, optional
         Random seed (integer) or np.random.RandomState instance to set
         the initial state of the random number generator for
         reproducibility. If None, a randomly initialized RandomState is

quantecon/gridtools.py

@@ -12,13 +12,13 @@
 def cartesian(nodes, order='C'):
     '''Cartesian product of a list of arrays
 
-    Parameters:
-    -----------
+    Parameters
+    ----------
     nodes: (list of 1d-arrays)
     order: ('C' or 'F') order in which the product is enumerated
 
-    Returns:
-    --------
+    Returns
+    -------
     out: (2d-array) each line corresponds to one point of the product space
     '''
 
@@ -49,15 +49,15 @@ def cartesian(nodes, order='C'):
 def mlinspace(a, b, nums, order='C'):
     '''Constructs a regular cartesian grid
 
-    Parameters:
-    -----------
+    Parameters
+    ----------
     a: (1d-array) lower bounds in each dimension
     b: (1d-array) upper bounds in each dimension
     nums: (1d-array) number of nodes along each dimension
     order: ('C' or 'F') order in which the product is enumerated
 
-    Returns:
-    --------
+    Returns
+    -------
     out: (2d-array) each line corresponds to one point of the product space
     '''
 

quantecon/markov/core.py

@@ -458,16 +458,14 @@ def simulate_indices(self, ts_length, init=None, num_reps=None,
         ts_length : scalar(int)
             Length of each simulation.
 
-        init : scalar(int) or array_like(int, ndim=1),
-               optional(default=None)
+        init : int or array_like(int, ndim=1), optional
             Initial state(s). If None, the initial state is randomly
             drawn.
 
         num_reps : scalar(int), optional(default=None)
             Number of repetitions of simulation.
 
-        random_state : scalar(int) or np.random.RandomState,
-                       optional(default=None)
+        random_state : int or np.random.RandomState, optional
             Random seed (integer) or np.random.RandomState instance to
             set the initial state of the random number generator for
             reproducibility. If None, a randomly initialized RandomState
@@ -558,8 +556,7 @@ def simulate(self, ts_length, init=None, num_reps=None, random_state=None):
         num_reps : scalar(int), optional(default=None)
             Number of repetitions of simulation.
 
-        random_state : scalar(int) or np.random.RandomState,
-                       optional(default=None)
+        random_state : int or np.random.RandomState, optional
             Random seed (integer) or np.random.RandomState instance to
             set the initial state of the random number generator for
             reproducibility. If None, a randomly initialized RandomState
@@ -700,8 +697,7 @@ def mc_sample_path(P, init=0, sample_size=1000, random_state=None):
     sample_size : scalar(int), optional(default=1000)
         The length of the sample path.
 
-    random_state : scalar(int) or np.random.RandomState,
-                   optional(default=None)
+    random_state : int or np.random.RandomState, optional
         Random seed (integer) or np.random.RandomState instance to set
         the initial state of the random number generator for
         reproducibility. If None, a randomly initialized RandomState is

quantecon/markov/ddp.py

@@ -134,8 +134,8 @@ class DiscreteDP(object):
        * discount factor beta,
 
        where `R[s, a]` is the reward for action `a` when the state is
-       `s` and `Q[s, a, s']` is the probability that the state in the
-       next period is `s'` when the current state is `s` and the action
+       `s` and `Q[s, a, s_next]` is the probability that the state in the
+       next period is `s_next` when the current state is `s` and the action
        chosen is `a`.
 
     2. `DiscreteDP(R, Q, beta, s_indices, a_indices)`
@@ -151,8 +151,8 @@ class DiscreteDP(object):
        where the pairs (`s_indices[0]`, `a_indices[0]`), ...,
        (`s_indices[L-1]`, `a_indices[L-1]`) enumerate feasible
        state-action pairs, and `R[i]` is the reward for action
-       `a_indices[i]` when the state is `s_indices[i]` and `Q[i, s']` is
-       the probability that the state in the next period is `s'` when
+       `a_indices[i]` when the state is `s_indices[i]` and `Q[i, s_next]` is
+       the probability that the state in the next period is `s_next` when
        the current state is `s_indices[i]` and the action chosen is
        `a_indices[i]`. With this formulation, `Q` may be represented by
        a scipy.sparse matrix.
@@ -213,7 +213,7 @@ class DiscreteDP(object):
 
           r(0, 0) = 5, r(0, 1) =10, r(1, 0) = -1
 
-    * Transition probabilities q(s'|s, a):
+    * Transition probabilities q(s_next|s, a):
 
           q(0|0, 0) = 0.5, q(1|0, 0) = 0.5,
           q(0|0, 1) = 0,   q(1|0, 1) = 1,
@@ -639,16 +639,16 @@ def solve(self, method='policy_iteration',
 
         Parameters
         ----------
-        method : str in {'value_iteration', 'vi', 'policy_iteration',
-                         'pi', 'modified_policy_iteration', 'mpi'},
-                 optinal(default='policy_iteration')
-            Solution method.
+        method : str, optinal(default='policy_iteration')
+            Solution method, str in {'value_iteration', 'vi',
+            'policy_iteration', 'pi', 'modified_policy_iteration',
+            'mpi'}.
 
         v_init : array_like(float, ndim=1), optional(default=None)
             Initial value function, of length n. If None, `v_init` is
             set such that v_init(s) = max_a r(s, a) for value iteration
             and policy iteration; for modified policy iteration,
-            v_init(s) = min_(s', a) r(s', a)/(1 - beta) to guarantee
+            v_init(s) = min_(s_next, a) r(s_next, a)/(1 - beta) to guarantee
             convergence.
 
         epsilon : scalar(float), optional(default=None)

quantecon/markov/random.py

@@ -35,8 +35,7 @@ def random_markov_chain(n, k=None, sparse=False, random_state=None):
         Whether to store the transition probability matrix in sparse
         matrix form.
 
-    random_state : scalar(int) or np.random.RandomState,
-                   optional(default=None)
+    random_state : int or np.random.RandomState, optional
         Random seed (integer) or np.random.RandomState instance to set
         the initial state of the random number generator for
         reproducibility. If None, a randomly initialized RandomState is
@@ -84,12 +83,11 @@ def random_stochastic_matrix(n, k=None, sparse=False, format='csr',
     sparse : bool, optional(default=False)
         Whether to generate the matrix in sparse matrix form.
 
-    format : str in {'bsr', 'csr', 'csc', 'coo', 'lil', 'dia', 'dok'},
-             optional(default='csr')
-        Sparse matrix format. Relevant only when sparse=True.
+    format : str, optional(default='csr')
+        Sparse matrix format, str in {'bsr', 'csr', 'csc', 'coo', 'lil',
+        'dia', 'dok'}. Relevant only when sparse=True.
 
-    random_state : scalar(int) or np.random.RandomState,
-                   optional(default=None)
+    random_state : int or np.random.RandomState, optional
         Random seed (integer) or np.random.RandomState instance to set
         the initial state of the random number generator for
         reproducibility. If None, a randomly initialized RandomState is
@@ -183,8 +181,7 @@ def random_discrete_dp(num_states, num_actions, beta=None,
         Whether to represent the data in the state-action pairs
         formulation. (If `sparse=True`, automatically set `True`.)
 
-    random_state : scalar(int) or np.random.RandomState,
-                   optional(default=None)
+    random_state : int or np.random.RandomState, optional
         Random seed (integer) or np.random.RandomState instance to set
         the initial state of the random number generator for
         reproducibility. If None, a randomly initialized RandomState is

quantecon/quad.py

@@ -464,7 +464,7 @@ def quadrect(f, n, a, b, kind='lege', *args, **kwargs):
         that accepts as its first argument a matrix representing points
         along each dimension (each dimension is a column). Other
         arguments that need to be passed to the function are caught by
-        *args and **kwargs
+        `*args` and `**kwargs`
 
     n : int or array_like(float)
         A length-d iterable of the number of nodes in each dimension

quantecon/random/utilities.py

@@ -22,8 +22,7 @@ def probvec(m, k, random_state=None, parallel=True):
     k : scalar(int)
         Dimension of each probability vectors.
 
-    random_state : scalar(int) or np.random.RandomState,
-                   optional(default=None)
+    random_state : int or np.random.RandomState, optional
         Random seed (integer) or np.random.RandomState instance to set
         the initial state of the random number generator for
         reproducibility. If None, a randomly initialized RandomState is
@@ -112,8 +111,7 @@ def sample_without_replacement(n, k, num_trials=None, random_state=None):
     num_trials : scalar(int), optional(default=None)
         Number of trials.
 
-    random_state : scalar(int) or np.random.RandomState,
-                   optional(default=None)
+    random_state : int or np.random.RandomState, optional
         Random seed (integer) or np.random.RandomState instance to set
         the initial state of the random number generator for
         reproducibility. If None, a randomly initialized RandomState is