Merge pull request #7236 from jorisvandenbossche/doc-fixes2

DOC: clean-up docstrings of option functions

Author: jorisvandenbossche

doc/source/api.rst

@@ -489,7 +489,6 @@ Serialization / IO / Conversion
    Series.to_frame
    Series.to_hdf
    Series.to_sql
-   Series.to_gbq
    Series.to_msgpack
    Series.to_json
    Series.to_sparse
@@ -1200,6 +1199,9 @@ Indexing, iteration
 
 .. currentmodule:: pandas
 
+.. autosummary::
+   :toctree: generated/
+
    Grouper
 
 .. currentmodule:: pandas.core.groupby
@@ -1226,8 +1228,11 @@ Computations / Descriptive Stats
 
 .. currentmodule:: pandas
 
+General utility functions
+-------------------------
+
 Working with options
---------------------
+~~~~~~~~~~~~~~~~~~~~
 
 .. autosummary::
    :toctree: generated/
@@ -1238,6 +1243,7 @@ Working with options
    set_option
    option_context
 
+
 ..
     HACK - see github issue #4539. To ensure old links remain valid, include
     here the autosummaries with previous currentmodules as a comment and add

pandas/core/config.py

@@ -224,45 +224,55 @@ def __doc__(self):
                                         opts_list=opts_list)
 
 _get_option_tmpl = """
-get_option(pat) - Retrieves the value of the specified option
+get_option(pat)
+
+Retrieves the value of the specified option.
 
 Available options:
+
 {opts_list}
 
 Parameters
 ----------
-pat - str/regexp which should match a single option.
-
-Note: partial matches are supported for convenience, but unless you use the
-full option name (e.g. x.y.z.option_name), your code may break in future
-versions if new options with similar names are introduced.
+pat : str
+    Regexp which should match a single option.
+    Note: partial matches are supported for convenience, but unless you use the
+    full option name (e.g. x.y.z.option_name), your code may break in future
+    versions if new options with similar names are introduced.
 
 Returns
 -------
-result - the value of the option
+result : the value of the option
 
 Raises
 ------
-OptionError if no such option exists
+OptionError : if no such option exists
+
+Notes
+-----
+The available options with its descriptions:
 
 {opts_desc}
 """
 
 _set_option_tmpl = """
-set_option(pat,value) - Sets the value of the specified option
+set_option(pat, value)
+
+Sets the value of the specified option.
 
 Available options:
+
 {opts_list}
 
 Parameters
 ----------
-pat - str/regexp which should match a single option.
-
-Note: partial matches are supported for convenience, but unless you use the
-full option name (e.g. x.y.z.option_name), your code may break in future
-versions if new options with similar names are introduced.
-
-value - new value of option.
+pat : str
+    Regexp which should match a single option.
+    Note: partial matches are supported for convenience, but unless you use the
+    full option name (e.g. x.y.z.option_name), your code may break in future
+    versions if new options with similar names are introduced.
+value :
+    new value of option.
 
 Returns
 -------
@@ -272,55 +282,72 @@ def __doc__(self):
 ------
 OptionError if no such option exists
 
+Notes
+-----
+The available options with its descriptions:
+
 {opts_desc}
 """
 
 _describe_option_tmpl = """
-describe_option(pat,_print_desc=False) Prints the description
-for one or more registered options.
+describe_option(pat, _print_desc=False)
+
+Prints the description for one or more registered options.
 
 Call with not arguments to get a listing for all registered options.
 
 Available options:
+
 {opts_list}
 
 Parameters
 ----------
-pat - str, a regexp pattern. All matching keys will have their
-      description displayed.
-
-_print_desc - if True (default) the description(s) will be printed
-             to stdout otherwise, the description(s) will be returned
-             as a unicode string (for testing).
+pat : str
+    Regexp pattern. All matching keys will have their description displayed.
+_print_desc : bool, default True
+    If True (default) the description(s) will be printed to stdout.
+    Otherwise, the description(s) will be returned as a unicode string
+    (for testing).
 
 Returns
 -------
 None by default, the description(s) as a unicode string if _print_desc
 is False
 
+Notes
+-----
+The available options with its descriptions:
+
 {opts_desc}
 """
 
 _reset_option_tmpl = """
-reset_option(pat) - Reset one or more options to their default value.
+reset_option(pat)
+
+Reset one or more options to their default value.
 
 Pass "all" as argument to reset all options.
 
 Available options:
+
 {opts_list}
 
 Parameters
 ----------
-pat - str/regex  if specified only options matching `prefix`* will be reset
-
-Note: partial matches are supported for convenience, but unless you use the
-full option name (e.g. x.y.z.option_name), your code may break in future
-versions if new options with similar names are introduced.
+pat : str/regex 
+    If specified only options matching `prefix*` will be reset. 
+    Note: partial matches are supported for convenience, but unless you
+    use the full option name (e.g. x.y.z.option_name), your code may break
+    in future versions if new options with similar names are introduced.
 
 Returns
 -------
 None
 
+Notes
+-----
+The available options with its descriptions:
+
 {opts_desc}
 """
 
@@ -337,6 +364,18 @@ def __doc__(self):
 
 
 class option_context(object):
+    """
+    Context manager to temporarily set options in the `with` statement context.
+
+    You need to invoke as ``option_context(pat, val, [(pat, val), ...])``.
+    
+    Examples
+    --------
+
+    >>> with option_context('display.max_rows', 10, 'display.max_columns', 5):
+            ...
+
+    """
 
     def __init__(self, *args):
         if not (len(args) % 2 == 0 and len(args) >= 2):
@@ -589,13 +628,13 @@ def _build_option_description(k):
     o = _get_registered_option(k)
     d = _get_deprecated_option(k)
 
-    s = u('%s: ') % k
+    s = u('%s : ') % k
     if o:
         s += u('[default: %s] [currently: %s]') % (o.defval,
                                                    _get_option(k, True))
 
     if o.doc:
-        s += '\n' + '\n    '.join(o.doc.strip().split('\n'))
+        s += '\n    '.join(o.doc.strip().split('\n'))
     else:
         s += 'No description available.\n'
 
@@ -604,7 +643,7 @@ def _build_option_description(k):
         s += (u(', use `%s` instead.') % d.rkey if d.rkey else '')
         s += u(')\n')
 
-    s += '\n'
+    s += '\n\n'
     return s
 
 
@@ -615,9 +654,9 @@ def pp_options_list(keys, width=80, _print=False):
     from itertools import groupby
 
     def pp(name, ks):
-        pfx = (name + '.[' if name else '')
+        pfx = ('- ' + name + '.[' if name else '')
         ls = wrap(', '.join(ks), width, initial_indent=pfx,
-                  subsequent_indent=' ' * len(pfx), break_long_words=False)
+                  subsequent_indent='  ', break_long_words=False)
         if ls and ls[-1] and name:
             ls[-1] = ls[-1] + ']'
         return ls

pandas/core/config_init.py

@@ -97,7 +97,6 @@
     a string with the desired format of the number. This is used
     in some places like SeriesFormatter.
     See core.format.EngFormatter for an example.
-
 """
 
 max_colwidth_doc = """
@@ -162,7 +161,6 @@
 
 pc_max_seq_items = """
 : int or None
-
     when pretty-printing a long sequence, no more then `max_seq_items`
     will be printed. If items are omitted, they will be denoted by the
     addition of "..." to the resulting string.
@@ -179,15 +177,13 @@
 
 pc_large_repr_doc = """
 : 'truncate'/'info'
-
     For DataFrames exceeding max_rows/max_cols, the repr (and HTML repr) can
     show a truncated table (the default from 0.13), or switch to the view from
     df.info() (the behaviour in earlier versions of pandas).
 """
 
 pc_mpl_style_doc = """
 : bool
-
     Setting this to 'default' will modify the rcParams used by matplotlib
     to give plots a more pleasing visual style by default.
     Setting this to None/False restores the values to their initial value.