Consistent and semantic CSS for signatures (original) (raw)

I propse to introduce a consistent set of semantic CSS classes for easier styling of the signature.

Current state

Example signature:

Axes. vlines ( x, y, linestyles='solid' )

The corresponding HTML looks like this:

<dt id="matplotlib.axes.Axes.vlines">
<code class="descclassname">Axes.</code>
<code class="descname">vlines</code>
<span class="sig-paren">(</span>
<em>x</em>, <em>y</em>, <em>linestyles='solid'</em>
<span class="sig-paren">)</span>

Proposed change

Use this set of semantic CSS classes:

• sig
  • sig-prename
  • sig-name
  • sig-paren
  • sig-param

These could simply be added to maintain compatibility with existing CSS files:

<dt id="matplotlib.axes.Axes.vlines" class="sig">
<code class="sig-prename descclassname">Axes.</code>
<code class="sig-name descname">vlines</code>
<span class="sig-paren">(</span>
<em class="sig-param">x</em>, <em class="sig-param">y</em>, <em class="sig-param">linestyles='solid'</em>
<span class="sig-paren">)</span>

In the long run descclassname and descname could be deprecated. Also one could debate if one should change the tags <code> and <em> to <span>, but I have no strong opinion on this.

This scheme can be extend when more complex signatures arise, as proposed in #4289. For example one could add classes sig-paramname and sig-paramvalue.