DOC: set_option docstring

[jseabold]

Warning. NIt-picky here.

Parking this here as I see it's not quite just a simple edit of a docstring. Might have time for a PR today. This is the current partial docstring of set_option. Maybe it's just me, but my eyes have a very hard time finding the actual parameters in here as it doesn't quite conform to the numpy docstring standard and the lines are not 79 characters so they wrap on my terminal (not obvious in the below but tough to grok in the terminal). Any else find this hard to read? Any thoughts on a better format? I think fixing the line lengths, moving the types to the same line as the option, and moving the default/currently to a new indented line at end of the description would go a long way.

display.chop_threshold: [default: None] [currently: None]
: float or None
        if set to a float value, all float values smaller then the given threshold
        will be displayed as exactly 0 by repr and friends.
display.colheader_justify: [default: right] [currently: right]
: 'left'/'right'
        Controls the justification of column headers. used by DataFrameFormatter.
display.column_space: [default: 12] [currently: 12]No description available.

display.date_dayfirst: [default: False] [currently: False]
: boolean
        When True, prints and parses dates with the day first, eg 20/01/2005
display.date_yearfirst: [default: False] [currently: False]
: boolean
        When True, prints and parses dates with the year first, eg 2005/01/20
display.encoding: [default: UTF-8] [currently: UTF-8]
: str/unicode
        Defaults to the detected encoding of the console.
        Specifies the encoding to be used for strings returned by to_string,
        these are generally strings meant to be displayed on the console.
display.expand_frame_repr: [default: True] [currently: True]
: boolean
        Whether to print out the full DataFrame repr for wide DataFrames across
        multiple lines, `max_columns` is still respected, but the output will
        wrap-around across multiple "pages" if it's width exceeds `display.width`.
display.float_format: [default: None] [currently: None]
: callable
        The callable should accept a floating point number and return
        a string with the desired format of the number. This is used
        in some places like SeriesFormatter.
        See core.format.EngFormatter for an example.
display.height: [default: 60] [currently: 60]
: int
        Deprecated.
        (Deprecated, use `display.max_rows` instead.)

[clham]

I agree this is hard to read. Thoughts on:

1. Removing the top block of options in the doc string, and just starting with Parameters
2. In the bottom section, aligning all of the descriptions to start just after their parameter's colon, e.g.

display.chop_threshold : [default: None] [currently: None]: float or None
                         If set to a float value, all float values smaller 
                         then the given threshold will be displayed as 
                         exactly 0 by repr and friends.

I'm happy to PR this if we can agree on a way that makes sense.

[jorisvandenbossche]

I also completely agree on this with @jseabold, but for the docstrings I already did a PR some time ago (#7236), so it has already improved a bit (but can certainly use some further improvement). See http://pandas.pydata.org/pandas-docs/stable/basics.html#working-with-package-options and http://pandas.pydata.org/pandas-docs/stable/generated/pandas.describe_option.html#pandas.describe_option.
I also personally think aligning the description with the colon after the parameters name is not a good idea, as this will make it align for every parameter differently (which will give a messy view I think). This is also how it is done in a Parameters section in a docstring.

But that is only for the docstring, I think the docs can use more improvement at the moment:

• Move the options section to a seperate file
• expand the section on the console output formatting (based on the section in the whatsnew files of 0.13, 0.13.1 and 0.14)
• provide an overview of the options is a table instead of raw text output of describe_option (bonuspoints for a sphinx directive that creates this table automatically by extracting the default value and description from the docstring :-))

I won't directly have the time for this, so if you want to take a try on this, certainly do!

[clham]

I guess I'll start tilting at this windmill. I'm not sure it will go well, but, I'm sure I'll learn something.

[jorisvandenbossche]

Nice! If you have any questions, just ask. Also, if you have already something, you can always open a PR to get initial feedback. You can always furhter update that PR. Here (http://pandas.pydata.org/pandas-docs/stable/contributing.html#contributing-to-the-documentation) are some basic docs about contributing to the documentation.

[clham]

@jorisvandenbossche This is coming along. I'm having a bit of trouble with display.column_space; it's not giving the expected results.

In [28]: df=pd.DataFrame(np.array([np.random.randn(6), np.random.randint(1,9,6)*.1, 
                         np.zeros(6)]).T, columns=['A', 'B', 'C'], dtype='float')

In [29]: pd.set_option('column_space', 12)

In [30]: df
Out[30]: 
          A    B  C
0  0.865356  0.1  0
1 -0.968568  0.2  0
2 -0.584314  0.8  0
3  0.347676  0.6  0
4  0.296440  0.8  0
5 -0.129957  0.2  0

In [31]: pd.set_option('column_space', 2)

In [32]: df
Out[32]: 
          A    B  C
0  0.865356  0.1  0
1 -0.968568  0.2  0
2 -0.584314  0.8  0
3  0.347676  0.6  0
4  0.296440  0.8  0
5 -0.129957  0.2  0

In [33]: pd.reset_option('column_space')

In line 30, I would have expected column B to be carried out to 12 places or characters. Am I misunderstanding how this is supposed to work? (I'll also add to the PR getting the description of this option to populate into describe_options

[jorisvandenbossche]

I actually don't know what this should do, @jreback?

[jreback]

no ideas the give the src/docs a search

[clham]

format.py states colspace "sets the minimum width of columns.", and frame.py states that colspace is depreciated, and to use col_space instead. -- this differs from init_config.py where it is refered to as column_space. In either case, it appears the docstring was never transferred, and, I still can't get it to work. Should I make a but out of this, or just roll it into this PR?

[jorisvandenbossche]

@clham I would say, just leave it out of the PR you are preparing now if you don't directly find it out, and maybe open a new issues about this to remember we have to find out what this exactly does, if it is deprecated or not and to take the appropriate action (or document it, or remove it)

[jreback]

pushing to 0.15.0 as #7578 was