Parameters and Returns headings are not visible

[francois-rozet]

Is your feature request related to a problem? Please describe.

"Parameters" and "Returns" headings are simple HTML paragraphes without any CSS class. They currently just look like plain text and there is no way to style them.

Describe the solution you'd like

The easiest solution is to assign a CSS class to these headings such that we can style them arbitrarily.
Additionally, it would be better if they were actual HTML headings (and we could choose the level).
The colons also look rather unpolished.

[pawamoy]

Would you like to send a PR? You'd need to update this

python/src/mkdocstrings_handlers/python/templates/material/_base/docstring/parameters.html

Line 3 in f2122d7

<p><strong>{{ section.title or "Parameters:" }}</strong></p>

to something like <span class="doc-section-title"> instead of <strong> (in every docstring template of course).
We can also drop the colons and add a CSS rule in the recommended style (in the docs), like .doc-section-title::after { content: ":"; } (though I think it will need an update in Griffe since it returns sections titles with the trailing colon).

As for making headings of these titles, I'm a bit against it (it would pollute the ToC IMO, and headings levels are quite limited: 5 max, with category headings enabled it will start to look bad with depth-2 objects). I'm still open to discussion of course 🙂

[francois-rozet]

Sure, I'll try to do that. By the way, currently there is not even <strong> around the "Parameters" and "Returns" if the section style is list.

python/src/mkdocstrings_handlers/python/templates/material/_base/docstring/parameters.html

Line 39 in d5ea1c5

<p>{{ section.title or "Parameters:" }}</p>

[pawamoy]

Yeah there are probably discrepancies between all the different sections, sections styles and themes. I should probably start to create tables like the Griffe ones (https://mkdocstrings.github.io/griffe/docstrings/) to keep track of everything. Feel free to harmonize things when/if you send a PR 🙂