DOC: some stylistic improvements to docstring rendering in documentation

[jorisvandenbossche]

This is a PR with some stylistic improvements to the docstring rendering in the documentation. The incentive was that I found the reference (docstring) documentation not always clearly organised.

Things I changed (mainly copied from the new numpy/scipy docs):

• reduced space around parameter description
• italic font for parameter types
• assure that colon after "Parameters" is on same line and some grey background in Parameter field to highlight the
• "See also" box: put link and description on same line
• light background color in code examples
• line under Notes and Examples section headers

You can see the result here: http://jorisvandenbossche.github.io/example-pandas-docs/html-docstring-rendering/generated/pandas.DataFrame.apply.html#pandas.DataFrame.apply
and compare with the original: http://pandas.pydata.org/pandas-docs/stable/generated/pandas.DataFrame.apply.html#pandas.DataFrame.apply

Each of the points is of course debatable and I can change some of them back. Maybe the grey background of the code cells (this also applies to the tutorial docs) and the grey highlighting of the "parameter" and "returns" field (this can alse be the full block as in eg http://docs.scipy.org/doc/numpy/reference/generated/numpy.reshape.html#numpy.reshape) is maybe the most debatable.

Style is of course always subjective :-) So what do you think?

[jreback]

+1

[cpcloud]

+1 on everything except the see also box. If things ever need to be wrapped I prefer the indented version that is below the class function

[cpcloud]

@jorisvandenbossche do you know if there's a way to get argument lists to wrap to the first parameter instead of just wrapping the line? Not a big deal don't spend too much time on it, I was just curious if there might be an easy fix for that.

[jorisvandenbossche]

@cpcloud What do you mean exactly with "argument lists to wrap to the first parameter instead of just wrapping the line"?

Regarding the see also box. My main incentive was: if you have some more references to other functions, the box can become quickly rather large (here is only one reference). But not a hard feeling about it, so no problem to change it back.

[jreback]

@jorisvandenbossche I actually like how numpy/scipy does it with the full block (and maybe not grey)....they use a reddish? (not saying copy it)...but just different

[jorisvandenbossche]

@jreback Yes, I was first planning to copy that, but this version I copied from the new style from numpy/scipy: http://docs.scipy.org/doc/numpy-dev/reference/generated/numpy.reshape.html#numpy.reshape

[cpcloud]

I mean that if the argument list of a function is wide enough so that it has to be wrapped, that it wraps by aligning to the first argument in the list. I'm on my phone (and I have no backticks) otherwise I'd give u an example. Does that make sense?

[jorisvandenbossche]

@cpcloud Aha, yes, I think I understand what you mean: you mean the arguments in the function signature (in the yellow part if this is linked to)

So eg here it could be wrapped: http://pandas.pydata.org/pandas-docs/dev/generated/pandas.tools.pivot.pivot_table.html#pandas.tools.pivot.pivot_table

But, I don't think it can be easily done (as far my very little css knowledge goes), because it is not in a seperate div.

[cpcloud]

Yeah. The variable width font makes that near impossible anyway. I suppose if the signature could be styled it would be possible. I might look into it if I get a chance. Anyway looks good!

[jorisvandenbossche]

OK, so I heard:

• keep the "See also" as it was original.
• maybe try the full grey block

Any other things?

@cpcloud The reason I tried to set the See also box on one line, is that it becomes rather large if you have some more references, like eg here:

[cpcloud]

@jorisvandenbossche i don't think that's a big deal, but it's really up to you ... i can be persuaded. my only concern was that for longer blurbs i wouldn't want to see things wrapped all in a single blob...if that won't happen then the way you originally wanted it is fine

[jorisvandenbossche]

@cpcloud I reverted the "see also", because the way I did it, there went something wrong when the explanation is long and needs a second line (and as I said, I am no css expert at all). So I will leave that as is.

@jreback For the parameter grey block, here is an example with a full block:
http://jorisvandenbossche.github.io/example-pandas-docs/html-docstring-rendering2/generated/pandas.DataFrame.apply.html#pandas.DataFrame.apply

[jreback]

+1 on full block (grey is fine)

[jorisvandenbossche]

OK, then for me in this state it can be merged (the commit is already with the full grey block).

[jtratner]

I'd like to take a look before we merge - thanks for working on this Joris!

[cpcloud]

@jorisvandenbossche echoing @jtratner 👍

[jreback]

@jtratner go ahead and merge when u r ready

[jtratner]

Thanks @jorisvandenbossche !