Aliki: Hard to discern method blocks visually

[gettalong]

I find it really hard to see where a method documentation starts and ends:

The headers "Args" and "Description" are much bigger than the method name although they are subordinate to it. This means when scrolling through the page it is hard - at least for me - to discern the part that belongs to a method.

I'm not sure whether this is the same problem but the right side bar is also quite useless in this case:

It is just a list of "Args" and "Description" entries without a hint for what.

[st0012]

Both Args and Usage headers are specific to this particular documentation's style. It's not something the theme inserts.
Currently RDoc doesn't enforce much format for individual method's documentation, and usually headers are avoided due to the same confusing effect you reported. But I also don't plan to limit the elements users can use based on the location (e.g. prohibit headers in method blocks).

If you ask me, the Args can simply be a list. And Description is simply redundant.

[gettalong]

@st0012 I get that you don't want to restrict the usage of elements. However, this is not just a visual problem but also a semantic problem.

• Each HTML page should have exactly one h1 heading, in the case of https://docs.ruby-lang.org/en/4.0/URI/RFC2396_Parser.html this would be class URI::RFC2396_Parser at the top.

• Then each further heading level should be correctly structured but isn't here. You can already see this in the right sidebar (or the second image). For example, the heading "Public instance methods" uses an h3 header and is shown underneath "Example" which is an h2 but this ordering is wrong.

  So semantically speaking the individual section headers "Attributes", "Public instance methods" and so on should be h2 and any documentation underneath should start with h3 headings.

• The right sidebar menu is automatically generated via Javascript from the headings. So it might also be useful to make the method names into headers so that they appear in the sidebar and we have an integrated quick jump menu.