Fields in functions are unnaturally big when using HTML5 writer

[Jackenmen]

Problem

Fields in functions look unnaturally big when using HTML5 writer
// I'm creating this from my comment in #916 since it's better to have it in separate issue.

Reproducible Project

Link: https://jack1142-red-prs.readthedocs.io/en/v3-bump_deps_html5_writer/framework_bank.html#redbot.core.bank.set_balance

Minimal reproduction:

.. function:: foo(bar)

    Description of the function

    :param bar: Description of param
    :type bar: :class:`str`

Error Logs/Results

Fields in functions look unnaturally big when using HTML5 writer (https://jack1142-red-prs.readthedocs.io/en/v3-bump_deps_html5_writer/framework_bank.html#redbot.core.bank.set_balance):

Expected Results

It should probably look the same as when using HTML4 writer (https://docs.discord.red/en/latest/framework_bank.html#redbot.core.bank.set_balance):

Environment Info

• Python Version: 3.8.2
• Sphinx Version: 3.0.3 (happens on 2.4.4 as well)
• RTD Theme Version: 0.5.0rc1

[agjohnson]

Mentioned in #916

[agjohnson]

So i might want to come back to this one. I actually think the small text is hard to read, and we only use smaller text in the case of footnotes currently. Using the smaller text here definitely reduces legibility without much gain.

[Jackenmen]

You might be right. It could be that the font size was not in fact the thing that I have the biggest issue with - maybe I just perceive the other elements of the layout differently in both looks and the font size was just the most visible reason why I would find the old look better.

I think (I'm honestly not sure at this point) that my real problem here is that the distinction between Parameters "header" and the actual parameters list feels less clear (same applies to Raises, Return type, etc). I know that technically color of header is exactly the same and that the font size of both is bigger in exactly same amount but something feels off (to me) about it. Only other thing that I see is the removed colon - that could actually be what was helping here though I'm not sure if the solution to that should necessarily be adding it back - maybe the distinction could be achieved differently.

[agjohnson]

Ahh that's a good point. It is at least missing the colon, that's an easy first step and one that should be resolved for a 0.5.0 release.

I think a larger overhaul of these styles could also help. Less spacing could be part of the difference you're describing, but perhaps more visual styling or even removing grid display of these items entirely would help communicate that these list items have special purpose.

I'm not convinced it's a good idea, but:

Anyways, I'd agree there is a bit more that we can do to this list and perhaps it makes sense to come back to this with some ideas in a follow up release.

[agjohnson]

Adding the colon was simple, ready in #941. It was also missing from general field lists, though that was a style choice. It's back everywhere now.

I'll leave this one open on 0.6 for now. I'd like to poke around some Sphinx and non-Sphinx examples of this to see if there is anything worth replicating in a larger change. This might be a good one to align with #938, so we're not maintain several ways of listing field lists like this.

Thanks for the feedback @jack1142 !

[Jackenmen]

Technically it's in the title but I just wanna mention that html4 writer uses smaller font size and html5 writer uses bigger font size, so it could be good to make them both the same size (from the comments above, I assume both would use the bigger size) for the time being.

[Blendify]

I prefer the bigger font size here and it keeps everything more consistent.

I visual improvement like @agjohnson showed is possible but I don't like that either because it uses a lot more vertical space which isn't so nice with long pages.

I am closing this as the original "bug" is a design choice to keep font size consistent.