Issue with field list formatting

[chrisjsewell]

Essentially code blocks (and maybe other elements?) within a field list are not given a max width.

Source text: https://github.com/aiidateam/aiida-core/blob/026f0bf6cacfff645610da5b30b6db426adbd173/docs/source/reference/rest_api.rst

    :attributes_filter:
        This key is used to specify which attributes of a specific object have to be returned.
        The desired attributes have to be provided as a comma-separated list of values.
        It is used in the endpoints ``/contents/attributes`` and ``/nodes``.
        Example:

        ::

            http://localhost:5000/api/v4/nodes/4fb10ef1/contents/attributes?attributes_filter=append_text,prepend_text

Rendered with pydata theme: https://175-77234579-gh.circle-artifacts.com/0/html/reference/rest_api.html#unique-filters

and if you remove the offending code block:

and the same file rendered with the RTD theme: https://137-77234579-gh.circle-artifacts.com/0/html/reference/rest_api.html#unique-filters

[jorisvandenbossche]

That doesn't look good!

From looking into this, it seems to be an issue with some css we inherit from sphinx (or the combination of that with css of our theme).

Those sphinx "field lists" have this css defining their grid (inherited from basic.css):

dl.field-list {
    display: grid;
    grid-template-columns: fit-content(30%) auto;
}

But the problem is that the auto is not very robust against large content, like the pre with a long line in this case.

A quick fix could be to override the above in your aiida-custom.css, eg with (which removes the grid altogether):

dl.field-list {
    display: block;
}

or, my quick attempt to cook something up with the css grid syntax that doesn't use auto for the content-part of the field list:

dl.field-list {
    display: grid;
    grid-template-columns: auto 80%;
}

BTW, we should maybe consider stop inheriting sphinx' basic.css. For that page, if you remove the full content of basic.css, it looks like:

The only problem is that bootstrap seems to override the left margin of description list's dd tag to be zero. Removing that override then gives the more default html look of a description list:

[jorisvandenbossche]

or, my quick attempt to cook something up with the css grid syntax that doesn't use auto for the content-part of the field list:

Or maybe the better fix is:

grid-template-columns: fit-content(30%) minmax(0, 1fr);

(from https://css-tricks.com/preventing-a-grid-blowout/)

[jorisvandenbossche]

@chrisjsewell also, if you prefer the more standard description list layout (also how RTD formats it), you can also use a sphinx definition list instead of field list. See https://pydata-sphinx-theme.readthedocs.io/en/latest/demo/lists_tables.html#definition-lists

[chrisjsewell]

Thanks for looking into this @jorisvandenbossche. Yes personally I would probably have used a definition list, but I didn't write this part of the documentation 😬 The CSS you suggest seems to do the job though, so I'll add that for now.

dl.field-list {
    display: grid;
    grid-template-columns: fit-content(30%) minmax(0, 1fr);
}

[choldgraf]

Just a note that I recently found this issue on the numpy NEP page as well: https://pydata-sphinx-theme.readthedocs.io/en/latest/demo/lists_tables.html

I'll try and make a quick PR to add the rule described above