Merge pull request #12893 from Carreau/doc-reformat

reformat docstring in IPython utils

IPython/utils/_process_common.py

@@ -52,10 +52,8 b' def process_handler(cmd, callback, stderr=subprocess.PIPE):'
       A command to be executed by the system, using :class:`subprocess.Popen`.
       If a string is passed, it will be run in the system shell. If a list is
       passed, it will be used directly as arguments.
-
     callback : callable
       A one-argument function that will be called with the Popen object.
-
     stderr : file descriptor number, optional
       By default this is set to ``subprocess.PIPE``, but you can also pass the
       value ``subprocess.STDOUT`` to force the subprocess' stderr to go into

IPython/utils/frame.py

@@ -28,12 +28,10 b' def extract_vars(*names,**kw):'
     *names : str
         One or more variable names which will be extracted from the caller's
         frame.
-
-    depth : integer, optional
+    **kw : integer, optional
         How many frames in the stack to walk when looking for your variables.
         The default is 0, which will use the frame where the call was made.
 
-
     Examples
     --------
     ::

IPython/utils/generics.py

@@ -22,7 +22,6 b' def complete_object(obj, prev_completions):'
         The object to complete.
     prev_completions : list
         List of attributes discovered so far.
-
     This should return the list of attributes in obj. If you only wish to
     add to the attributes already discovered normally, return
     own_attrs + prev_completions.

IPython/utils/io.py

@@ -114,10 +114,8 b' class Tee(object):'
         ----------
         file_or_name : filename or open filehandle (writable)
           File that will be duplicated
-
         mode : optional, valid mode for open().
           If a filename was give, open with this mode.
-
         channel : str, one of ['stdout', 'stderr']
         """
         if channel not in ['stdout', 'stderr']:
@@ -196,7 +194,6 b" def temp_pyfile(src, ext='.py'):"
     ----------
     src : string or list of strings (no need for ending newlines if list)
       Source code to be written to the file.
-
     ext : optional, string
       Extension for the generated file.
 

IPython/utils/ipstruct.py

@@ -43,14 +43,13 b' class Struct(dict):'
 
         Parameters
         ----------
-        args : dict, Struct
+        *args : dict, Struct
             Initialize with one dict or Struct
-        kw : dict
+        **kw : dict
             Initialize with key, value pairs.
 
         Examples
         --------
-
         >>> s = Struct(a=10,b=30)
         >>> s.a
         10
@@ -68,7 +67,6 b' class Struct(dict):'
 
         Examples
         --------
-
         >>> s = Struct()
         >>> s['a'] = 10
         >>> s.allow_new_attr(False)
@@ -95,7 +93,6 b' class Struct(dict):'
 
         Examples
         --------
-
         >>> s = Struct()
         >>> s.a = 10
         >>> s.a
@@ -130,7 +127,6 b' class Struct(dict):'
 
         Examples
         --------
-
         >>> s = Struct(a=10)
         >>> s.a
         10
@@ -155,7 +151,6 b' class Struct(dict):'
 
         Examples
         --------
-
         >>> s = Struct(a=10,b=30)
         >>> s2 = Struct(a=20,c=40)
         >>> s += s2
@@ -170,7 +165,6 b' class Struct(dict):'
 
         Examples
         --------
-
         >>> s1 = Struct(a=10,b=30)
         >>> s2 = Struct(a=20,c=40)
         >>> s = s1 + s2
@@ -186,7 +180,6 b' class Struct(dict):'
 
         Examples
         --------
-
         >>> s1 = Struct(a=10,b=30)
         >>> s2 = Struct(a=40)
         >>> s = s1 - s2
@@ -202,7 +195,6 b' class Struct(dict):'
 
         Examples
         --------
-
         >>> s1 = Struct(a=10,b=30)
         >>> s2 = Struct(a=40)
         >>> s1 -= s2
@@ -236,7 +228,6 b' class Struct(dict):'
 
         Examples
         --------
-
         >>> s = Struct(a=10,b=30)
         >>> s2 = s.copy()
         >>> type(s2) is Struct
@@ -251,7 +242,6 b' class Struct(dict):'
 
         Examples
         --------
-
         >>> s = Struct(a=10)
         >>> s.hasattr('a')
         True
@@ -284,7 +274,7 b' class Struct(dict):'
 
         Parameters
         ----------
-        __loc_data : dict, Struct
+        __loc_data__ : dict, Struct
             The data to merge into self
         __conflict_solve : dict
             The conflict policy dict.  The keys are binary functions used to
@@ -292,12 +282,11 b' class Struct(dict):'
             the keys the conflict resolution function applies to.  Instead of
             a list of strings a space separated string can be used, like
             'a b c'.
-        kw : dict
+        **kw : dict
             Additional key, value pairs to merge in
 
         Notes
         -----
-
         The `__conflict_solve` dict is a dictionary of binary functions which will be used to
         solve key conflicts.  Here is an example::
 
@@ -338,7 +327,6 b' class Struct(dict):'
 
         Examples
         --------
-
         This show the default policy:
 
         >>> s = Struct(a=10,b=30)

IPython/utils/path.py

@@ -109,7 +109,7 b' def get_py_filename(name, force_win32=None):'
         raise IOError('File `%r` not found.' % name)
 
 
-def filefind(filename, path_dirs=None):
+def filefind(filename: str, path_dirs=None) -> str:
     """Find a file by looking through a sequence of paths.
 
     This iterates through a sequence of paths looking for a file and returns
@@ -139,7 +139,12 b' def filefind(filename, path_dirs=None):'
 
     Returns
     -------
-    Raises :exc:`IOError` or returns absolute path to file.
+    path : str
+        returns absolute path to file.
+
+    Raises
+    ------
+    IOError
     """
 
     # If paths are quoted, abspath gets confused, strip them...
@@ -178,7 +183,6 b' def get_home_dir(require_writable=False) -> str:'
 
     Parameters
     ----------
-
     require_writable : bool [default: False]
         if True:
             guarantees the return value is a writable directory, otherwise

IPython/utils/text.py

@@ -252,7 +252,6 b' def indent(instr,nspaces=4, ntabs=0, flatten=False):'
 
     Parameters
     ----------
-
     instr : basestring
         The string to be indented.
     nspaces : int (default: 4)
@@ -266,7 +265,6 b' def indent(instr,nspaces=4, ntabs=0, flatten=False):'
 
     Returns
     -------
-
     str|unicode : string indented by ntabs and nspaces.
 
     """
@@ -390,7 +388,6 b' def wrap_paragraphs(text, ncols=80):'
 
     Returns
     -------
-
     list of complete paragraphs, wrapped to fill `ncols` columns.
     """
     paragraph_re = re.compile(r'\n(\s*\n)+', re.MULTILINE)
@@ -651,7 +648,6 b' def compute_item_matrix(items, row_first=False, empty=None, *args, **kwargs) :'
 
     Parameters
     ----------
-
     items
         list of strings to columize
     row_first : (default False)
@@ -666,14 +662,11 b' def compute_item_matrix(items, row_first=False, empty=None, *args, **kwargs) :'
 
     Returns
     -------
-
     strings_matrix
-
         nested list of string, the outer most list contains as many list as
         rows, the innermost lists have each as many element as columns. If the
         total number of elements in `items` does not equal the product of
         rows*columns, the last element of some lists are filled with `None`.
-
     dict_info
         some info to make columnize easier:
 
@@ -713,14 +706,11 b" def columnize(items, row_first=False, separator=' ', displaywidth=80, spread=Fa"
     ----------
     items : sequence of strings
         The strings to process.
-
     row_first : (default False)
         Whether to compute columns for a row-first matrix instead of
         column-first (default).
-
     separator : str, optional [default is two spaces]
         The string that separates columns.
-
     displaywidth : int, optional [default is 80]
         Width of the display in number of characters.
 

IPython/utils/tokenutil.py

@@ -28,7 +28,6 b' def line_at_cursor(cell, cursor_pos=0):'
     
     Parameters
     ----------
-    
     cell: str
         multiline block of text
     cursor_pos: integer
@@ -36,7 +35,6 b' def line_at_cursor(cell, cursor_pos=0):'
     
     Returns
     -------
-    
     (line, offset): (string, integer)
         The line with the current cursor, and the character offset of the start of the line.
     """
@@ -66,7 +64,6 b' def token_at_cursor(cell, cursor_pos=0):'
     
     Parameters
     ----------
-    
     cell : unicode
         A block of Python code
     cursor_pos : int