DOC: increased width of text area (#4159)

[jorisvandenbossche]

See #4159

This adds a minimum and maximum width of the text area (instead of one fixed value of, at the moment 600px), and I also increased the maximum value (from 600 to 840).

I took the values of the standard sphinx docs which are 780-1080 (minus 240 for the sidebar, in the standard sphinx docs the width is defined for the whole body, here only for the main text area)

[jreback]

@y-p I think u put the max there originally
any issue?

[ghost]

yes I did. It's considered typographic best practice to limit
line width to a certain number of characters to enhance readability.

I'm pleased with the way the docs look now, don't you agree?

[jreback]

I think limiting is good....this just increases the limint a bit (they take up about 1/2 of the screen on my (big) monitor)...what is considered 'normal'? pretty much filling the screen or showing a certain num of characters?

[jtratner]

Here's how this build looks online (if you don't have time to build): http://jtratner.github.io/example-pandas-docs/doc-build/html/index.html

[jreback]

I am +1 on this....its just a bit wider, but to me (my 2c) makes a big diff, many less horizontal scrollbars in the code exmples

[ghost]

Thanks for the link, that helps.

I was motivated by this talk: https://www.youtube.com/watch?v=8J6HuvosP0s
summary here

Expressly, the text width should not be determined by the width of your screen.
The talk gives gives 45-90 characters per line as a rule of thumb, or the length of
2-3 english alphabets back to back.

The current style follows this, the new style exceeds it and I find it (slightly) too wide.
I'm note sure if it's a matter of taste, DPI or something else.

jeff, can you link to a code example that makes you scroll? maybe it's fixable,
maybe there's another issue (different systems?) at play, or maybe I'm just wrong.

[ghost]

ok, I see the problem with the code examples.

It looks like this patch roughly doubles the text width. I think most of the issue
can be resolved by a much smaller increase of 25-50% (less is better) and without
throwing readability out the window.

Some code examples produce unreasonably wide output (dataframes that doesn't summarize, etc),
trashing the prose styling to accomodate them is the wrong choice IMO, they should be reformatted
or left to scroll. perhaps some display settings need to be tweaked in the ipython preamble?

[ghost]

Also, a majority of the offending lines in the code snippets are handicapped by
the wide IPython prompt, and the running input counter which curiously starts with 1
in the first chapter and ends up >1000 in the last one.

Converting that prompt into >>> would improve things as well.

[jtratner]

@y-p it would be nice if there were a way to reset the numbering on the input counter (but I didn't see a setting).

[jreback]

http://ipython.org/ipython-doc/dev/development/ipython_directive.html

ipython_promptin and ipython_promptout

[jorisvandenbossche]

@y-p I completely understand that you limited the max width (in the previous version it was indeed way to wide for a wide screen), but my main point that it is now too small is the scrolling with the code snippets (as I explained in the original issue #4159)

At the moment with this PR the width of the actual text area (so without the padding of 30px at each side) is increased from 540 px to 780 px, so an increase of 44.44 % to be exactly (so within your range of 25-50% :-)

But if I can make it a little bit smaller while displaying the code snippets that's fine (eg with the ipython prompt starting at 1 each time)

[ghost]

my mistake. 50% is way too much then.

by all means, make the text display a little wider, but don't be guided by the width
outliers of code lines, fix (or ignore) those snippets instead/

I suggest a a text width of 640-660px would be a good compromise, in combination with
the ipython prompt getting knocked down that should take care of the code snippets
as well.

[jorisvandenbossche]

I did some testing with the width in firefox for a normal code snippet (so not in a bulleted list):

• to only display 80 chars (without prompt) on my screen, max-width has to be 720px wide (so then actual text area is 660 px)
• to display standard python prompt (>>> ) + 80 chars: 740 px
• to display ipython prompt (In [99]: )+ 80 chars: 780 px
• to display ipython prompt (In [999]: )+ 80 chars: 790 px

So the max of 840 px (as now in the PR) could be a little bit lower.

Another option of course is to adapt all code snippets that they are shorter than the standard 78 characters, but that zou need a scrollbar to see the whole code snippet as is the case for some now, I find really awkward.

What do you think? I can eg put the max-width at 800 px instead of 840 px?

[ghost]

I'm fine with max-width of 720px. I'm puzzled why you seem to come
up with much larger required width. Maybe we're looking at different parts
of the documentation. what chapter are you trying these settings out on?

[jorisvandenbossche]

For example in the basic functionality section http://pandas.pydata.org/pandas-docs/dev/basics.html, on my computer there are about 20 code snippets on that page that need a horizontal scrollbar, while most of them (not all) are no outliers but within the standard of 78 chars.

For the values above, I just added a code snippet with a line of exactly 80 chars with and without prompts, and looked in firefox with the developers tools (there you can adapt the css and directly see the result) what the value of max-width had to be to display the line.

Would it be an option to limit the width of the text paragraphs but let the code snippets be a little bit wider?

[ghost]

I went ahead and modified the IPython prompt and used 720px for the max-width,
and on the page you mentioned I only get 3 code cells with scrollbars, 2 of which
have a width of at least 120 characters due to bad output formatting.
the remaining cell is the output of pd.describe_option() which can be corrected,
or just endured individually.

Perhaps there's a DPI or font fallback issue at play here, so our systems display
the output differently. In any case, if you update your PR to use max-width=720px
and update the prompt, I'm +1 on that.

[jorisvandenbossche]

@y-p What do you mean with 'update the prompt'? Convert it to >>>?

I asked MinRK from IPython about the ever increasing prompt numbers, and it seems that it is because an old version of ipython_directive in the pandas repo. I will add a commit to fix that. With that every page should start at prompt number 1, this will also make a little bit room.

[jtratner]

new version - http://jtratner.github.io/example-pandas-docs/html/index.html .for future reference, you can (I believe) push to a gh-pages branch on any project and get github pages for free. I was rushing through which is why URLs were weird.

[jreback]

numbering looks good...how about we split difff on max-wdith....720? 750?

it actually is a little wide here I think (too much whitespace)

[jreback]

@jtratner can you put a revised version up with say 750 max-width?

[jtratner]

http://jtratner.github.io/example-pandas-docs/html-750px/index.html
http://jtratner.github.io/example-pandas-docs/html-720px/index.html
http://jtratner.github.io/example-pandas-docs/html-780px/index.html

[ghost]

@jreback, my vote is for 720 and '>>>', go ahead and merge what works for you all.

[jreback]

I agree

@jorisvandenbossche can h make the change to 720 max width

[jorisvandenbossche]

OK, 720 max is fine. I updated the commit.
@jtratner, thanks for the build examles!

What about the ipython prompt? Do I also change that to >>>. My personal preference is to keep the ipython prompt (certainly now the numbering is less of a problem), but of course my preference is not that important.

[jreback]

I think the numbers are good. (now that they r reset each file)