DOC: Titles of long function names in API Reference truncated and horizontal scroll bar in code examples in 3 column layout

[DietBru]

As shown in the bottom portion of the screenshot below, the HTML documentation does not use the full window width of the browser. For some titles, the default width is not enough (red square in screenshot). Adding the following lines to the file doc/source/_static/scipy.css

.bd-main .bd-content .bd-article-container {
  max-width: 100%;  /* default is 60em */
}
.bd-page-width {
  max-width: 100%;  /* default is 88rem */
}

lets the center column use the full width (top portion of screenshot). Details can be found in the pydata-sphinx-theme docs.

[ilayn]

This might have other consequences though. In particular, using full page has a potential readability issue https://baymard.com/blog/line-length-readability

If this is not a very common problem, probably good thing is to leave it alone.

[melissawm]

I think we can experiment with maybe not 100% but something larger than the default. For information, this is where the page width comes from: https://pydata-sphinx-theme.readthedocs.io/en/latest/user_guide/layout.html#horizontal-spacing

(I just realized you had already linked it @DietBru 🤦🏻‍♀️ sorry!)

[DietBru]

This might have other consequences though. In particular, using full page has a potential readability issue https://baymard.com/blog/line-length-readability

I would argue that the recommended <75 character margin widths are plausible for longer chunks of continuous texts but not necessarily for the function style reference of SciPy, because:

• Paragraphs tend to be very short and are often indented as well. Hence, there is additional layout structure for the eyes to not get lost within the paragraph.
• The user may adjust the window width or respective window font size to their personal preference. The text flow will adapt automatically. Fixed narrow margins just vary the white space of the borders.
• Function references are frequently not read from top to bottom but are skimmed. Hence, seeing a larger portion without scrolling is beneficial, in my opinion.
• That this recommendation is not valid for all circumstances can be seen by looking at the image captions at https://baymard.com/blog/line-length-readability — there the text spans the full width of the image.

If not allowing full width marigns, increasing them by a little bit would already be beneficial: Code examples, like in special.airye display only 74 characters per line though the code is 80 characters wide. Hence, manual horizontal scrolling is needed. The Contributor Guide on the other hand suggests a maximum width of 88 characters.

[ilayn]

The regular users won't have any problem with any width, they can just like or get annoyed. The readability is for the impaired and folks with dyslexia and alike who have issues with "returning the carriage to the newline". Also, letting user adjust window size for readability is a no-no for frontend. Here is another example

But anyways, I'm not knowledgeable or passionate enough to defend any position about it.

[DietBru]

But anyways, I'm not knowledgeable or passionate enough to defend any position about it.

To make progress on this topic, let's try focus on the layout problems at hand to perhaps find a better solution (I changed the issue title accordingly):

1. Long function/class names title truncated: if the function name is longer than ≈41 charachters, e.g., scipy.interpolate.CloughTocher2DInterpolator, its title will be truncated. The same thing happens in the top and bottom navigation entries. A solution would be to not include to module name, i.e, only use CloughTocher2DInterpolator there.
2. Code examples are only 74 characters wide (without >>> only 70 char.) though the Contributor Guide suggests 88 characters. A solution would to increase width of those boxes by 25% (or the width of columns int API reference). For reference: the width of this Github comment block is ≈119 characters wide.

Note these issues appear only if the browser window is wide enough to have a three column layout. For narrower browser windows, the one- and two column layout has more characters per line.

[ilayn]

Both are OK with me.

For item 1 probably not truncating the breadcrumbs is a better solution so that the context is obvious.

[melissawm]

Thanks for thee discussion folks. I am going to loop in accessibility people who can maybe help us evaluate the best decision here.

[asmeurer]

Why not just wrap the header text? This is what the Furo theme does, for example. I'm not a CSS expert, but you might even be able to use something like <wbr> to make it wrap on the dot instead of the middle of the function name (https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_text/Wrapping_breaking_text#the_wbr_element).