Mis-render of "side" titles for docstring parameters

[bryevdv]

cc @choldgraf @jorisvandenbossche

As the viewport narrows:

Leading eventually to:

I would personally like to see the "Parameters" and "Keyword Arguments" headings above their respective lists, rather than off to the side, with the lists of parameters and their docs getting full (or nearly full) width, Apart from the amusing results above on narrow viewports, it's also a huge waste of vertical space below the headings on wide viewports:

[drammock]

we (MNE-Python) fixed the wrapping problem in our local CSS like this:

dl.field-list {
    grid-template-columns: auto 1fr;
}

I can put in a PR if that seems an acceptable solution for the general case.

[bryevdv]

Not sure what is different about our setup but that change does not seem to have much or any effect (verified the stylesheet loaded in the browser has the change)

[drammock]

oops, you're right, sorry. I remembered dealing with this issue, and I naively checked the browser console to see what rules from our custom CSS were applying to that node or its parent. But if I look at the PR where I actually tackled the problem my past self says that I expressly didn't fix the wrapping problem, which probably needs to be addressed by adjusting the media breakpoints in the theme (?).

[drammock]

...although, strangely, it doesn't seem to happen on the MNE-Python site, so maybe I did eventually fix it in a different PR? Will dig deeper.

[choldgraf]

I'm totally +1 on fixing this, but not sure what to do. IF somebody figures out a CSS fix for it I am happy to review a PR!

[choldgraf]

@bryevdv it would be helpful if you provided a link to a page with this problem

[bryevdv]

@choldgraf https://docs.bokeh.org/en/2.3.3/docs/reference/plotting.html#bokeh.plotting.Figure.bezier

Just reiterating that personally I think a structural change that splits each args section into its own separate dl might be preferable (again I'd like to see those as headers above each list, not off to the side, taking up huge columns of empty space below)

[drammock]

I can reproduce the problem @bryevdv is seeing, and I confirm that my suggested CSS rule doesn't fix it on the Bokeh site. I don't have time right now to rigorously compare the CSS files and conf.pys to find what the source of the different behavior might be.

Just reiterating that personally I think a structural change that splits each args section into its own separate dl might be preferable

in some quick-but-not-rigorous testing, this is possible with:

dl.field-list {
    display: unset;
}

or

dl.field-list {
    display: grid;
    grid-template-columns: unset;

If the theme maintainers want to go that route, however, I'd expect some corresponding style changes to the dt elements and/or a small indent on the dd elements, to make the dts stand out more as heading-like things and the dds as more content-like things.

[choldgraf]

this is an autodoc specific thing right? I am happy to special-case autodoc output with some CSS that only works for it, or something like that

[bryevdv]

@choldgraf we use Google style docstrings with sphinx.ext.napoleon It is supposed to outputs ReST like

:param arg1: Description of `arg1`
:type arg1:

by default. AFAIK those are processed by the sphinx std python domain.

[bryevdv]

@drammock yah that could use some tweaking but it's already much better, I will probably put this with some tweaks in the next Bokeh release as a stopgap, just because of how much it improves (looks good on narrow viewport too). Thank you!

[jorisvandenbossche]

The whole docstring / API page styling can probably use a redesign (there were some other autodoc related changes due to sphinx as well: #460)

I agree that having the "Parameters" etc in a separate column is not very robust long term, it will always give problems when the screen gets smaller (in addition to wasting space).
This is actually inherited from the basic.css which sets dl.field-list to display: grid;

As usual, we can get some inspiration from Furo: https://pradyunsg.me/furo/reference/api/. It puts the title above the content (not inheriting from basic.css gives that automatically), and adds a small indentation to the content (and in addition also makes the title upper case). CSS: https://github.com/pradyunsg/furo/blob/main/src/furo/assets/styles/content/_api.sass

[choldgraf]

+1 to doing whatever Furo does :-)