Skip to content

Commit 439f5e6

Browse files
pawamoypawamoy
committed
refactor: Improve display of paragraphs in docstring sections
1 parent 6530b6e commit 439f5e6

File tree

10 files changed

+101
-34
lines changed

10 files changed

+101
-34
lines changed

‎docs/usage/customization.md

+1
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ The following CSS classes are used in the generated HTML:
2222
- `doc-labels`: on `span`s wrapping the object's labels
2323
- `doc-label`: on `small` elements containing a label
2424
- `doc-label-LABEL`: same, where `LABEL` is replaced by the actual label
25+
- `doc-md-description`: on `div`s containing HTML descriptions converted from Markdown docstrings
2526

2627
/// admonition | Example with colorful labels
2728
type: example

‎src/mkdocstrings_handlers/python/templates/material/_base/docstring/attributes.html

+12-3
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,11 @@
2121
{% endwith %}
2222
{% endif %}
2323
</td>
24-
<td>{{ attribute.description|convert_markdown(heading_level, html_id) }}</td>
24+
<td>
25+
<div class="doc-md-description">
26+
{{ attribute.description|convert_markdown(heading_level, html_id) }}
27+
</div>
28+
</td>
2529
</tr>
2630
{% endfor %}
2731
</tbody>
@@ -39,7 +43,10 @@
3943
(<code>{% include "expression.html" with context %}</code>)
4044
{% endwith %}
4145
{% endif %}
42-
– {{ attribute.description|convert_markdown(heading_level, html_id) }}
46+
–
47+
<div class="doc-md-description">
48+
{{ attribute.description|convert_markdown(heading_level, html_id) }}
49+
</div>
4350
</li>
4451
{% endfor %}
4552
</ul>
@@ -58,7 +65,9 @@
5865
<tr>
5966
<td><code>{{ attribute.name }}</code></td>
6067
<td class="doc-attribute-details">
61-
{{ attribute.description|convert_markdown(heading_level, html_id) }}
68+
<div class="doc-md-description">
69+
{{ attribute.description|convert_markdown(heading_level, html_id) }}
70+
</div>
6271
<p>
6372
{% if attribute.annotation %}
6473
<span class="doc-attribute-annotation">

‎src/mkdocstrings_handlers/python/templates/material/_base/docstring/other_parameters.html

+12-3
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,11 @@
2121
{% endwith %}
2222
{% endif %}
2323
</td>
24-
<td>{{ parameter.description|convert_markdown(heading_level, html_id) }}</td>
24+
<td>
25+
<div class="doc-md-description">
26+
{{ parameter.description|convert_markdown(heading_level, html_id) }}
27+
</div>
28+
</td>
2529
</tr>
2630
{% endfor %}
2731
</tbody>
@@ -39,7 +43,10 @@
3943
(<code>{% include "expression.html" with context %}</code>)
4044
{% endwith %}
4145
{% endif %}
42-
– {{ parameter.description|convert_markdown(heading_level, html_id) }}
46+
–
47+
<div class="doc-md-description">
48+
{{ parameter.description|convert_markdown(heading_level, html_id) }}
49+
</div>
4350
</li>
4451
{% endfor %}
4552
</ul>
@@ -58,7 +65,9 @@
5865
<tr>
5966
<td><code>{{ parameter.name }}</code></td>
6067
<td class="doc-param-details">
61-
{{ parameter.description|convert_markdown(heading_level, html_id) }}
68+
<div class="doc-md-description">
69+
{{ parameter.description|convert_markdown(heading_level, html_id) }}
70+
</div>
6271
<p>
6372
{% if parameter.annotation %}
6473
<span class="doc-param-annotation">

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

+12-3
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,11 @@
2222
{% endwith %}
2323
{% endif %}
2424
</td>
25-
<td>{{ parameter.description|convert_markdown(heading_level, html_id) }}</td>
25+
<td>
26+
<div class="doc-md-description">
27+
{{ parameter.description|convert_markdown(heading_level, html_id) }}
28+
</div>
29+
</td>
2630
<td>
2731
{% if parameter.default %}
2832
{% with expression = parameter.default %}
@@ -49,7 +53,10 @@
4953
(<code>{% include "expression.html" with context %}</code>)
5054
{% endwith %}
5155
{% endif %}
52-
– {{ parameter.description|convert_markdown(heading_level, html_id) }}
56+
–
57+
<div class="doc-md-description">
58+
{{ parameter.description|convert_markdown(heading_level, html_id) }}
59+
</div>
5360
</li>
5461
{% endfor %}
5562
</ul>
@@ -68,7 +75,9 @@
6875
<tr>
6976
<td><code>{{ parameter.name }}</code></td>
7077
<td class="doc-param-details">
71-
{{ parameter.description|convert_markdown(heading_level, html_id) }}
78+
<div class="doc-md-description">
79+
{{ parameter.description|convert_markdown(heading_level, html_id) }}
80+
</div>
7281
<p>
7382
{% if parameter.annotation %}
7483
<span class="doc-param-annotation">

‎src/mkdocstrings_handlers/python/templates/material/_base/docstring/raises.html

+11-3
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,11 @@
1919
{% endwith %}
2020
{% endif %}
2121
</td>
22-
<td>{{ raises.description|convert_markdown(heading_level, html_id) }}</td>
22+
<td>
23+
<div class="doc-md-description">
24+
{{ raises.description|convert_markdown(heading_level, html_id) }}
25+
</div>
26+
</td>
2327
</tr>
2428
{% endfor %}
2529
</tbody>
@@ -37,7 +41,9 @@
3741
{% endwith %}
3842
–
3943
{% endif %}
40-
{{ raises.description|convert_markdown(heading_level, html_id) }}
44+
<div class="doc-md-description">
45+
{{ raises.description|convert_markdown(heading_level, html_id) }}
46+
</div>
4147
</li>
4248
{% endfor %}
4349
</ul>
@@ -62,7 +68,9 @@
6268
</span>
6369
</td>
6470
<td class="doc-raises-details">
65-
{{ raises.description|convert_markdown(heading_level, html_id) }}
71+
<div class="doc-md-description">
72+
{{ raises.description|convert_markdown(heading_level, html_id) }}
73+
</div>
6674
</td>
6775
</tr>
6876
{% endfor %}

‎src/mkdocstrings_handlers/python/templates/material/_base/docstring/receives.html

+12-3
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,11 @@
2222
{% endwith %}
2323
{% endif %}
2424
</td>
25-
<td>{{ receives.description|convert_markdown(heading_level, html_id) }}</td>
25+
<td>
26+
<div class="doc-md-description">
27+
{{ receives.description|convert_markdown(heading_level, html_id) }}
28+
</div>
29+
</td>
2630
</tr>
2731
{% endfor %}
2832
</tbody>
@@ -42,7 +46,10 @@
4246
{% if receives.name %}){% endif %}
4347
{% endwith %}
4448
{% endif %}
45-
– {{ receives.description|convert_markdown(heading_level, html_id) }}
49+
–
50+
<div class="doc-md-description">
51+
{{ receives.description|convert_markdown(heading_level, html_id) }}
52+
</div>
4653
</li>
4754
{% endfor %}
4855
</ul>
@@ -71,7 +78,9 @@
7178
{% endif %}
7279
</td>
7380
<td class="doc-receives-details">
74-
{{ receives.description|convert_markdown(heading_level, html_id) }}
81+
<div class="doc-md-description">
82+
{{ receives.description|convert_markdown(heading_level, html_id) }}
83+
</div>
7584
{% if receives.name and receives.annotation %}
7685
<p>
7786
<span class="doc-receives-annotation">

‎src/mkdocstrings_handlers/python/templates/material/_base/docstring/returns.html

+12-3
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,11 @@
2222
{% endwith %}
2323
{% endif %}
2424
</td>
25-
<td>{{ returns.description|convert_markdown(heading_level, html_id) }}</td>
25+
<td>
26+
<div class="doc-md-description">
27+
{{ returns.description|convert_markdown(heading_level, html_id) }}
28+
</div>
29+
</td>
2630
</tr>
2731
{% endfor %}
2832
</tbody>
@@ -42,7 +46,10 @@
4246
{% if returns.name %}){% endif %}
4347
{% endwith %}
4448
{% endif %}
45-
– {{ returns.description|convert_markdown(heading_level, html_id) }}
49+
–
50+
<div class="doc-md-description">
51+
{{ returns.description|convert_markdown(heading_level, html_id) }}
52+
</div>
4653
</li>
4754
{% endfor %}
4855
</ul>
@@ -71,7 +78,9 @@
7178
{% endif %}
7279
</td>
7380
<td class="doc-returns-details">
74-
{{ returns.description|convert_markdown(heading_level, html_id) }}
81+
<div class="doc-md-description">
82+
{{ returns.description|convert_markdown(heading_level, html_id) }}
83+
</div>
7584
{% if returns.name and returns.annotation %}
7685
<p>
7786
<span class="doc-returns-annotation">

‎src/mkdocstrings_handlers/python/templates/material/_base/docstring/warns.html

+11-3
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,11 @@
1919
{% endwith %}
2020
{% endif %}
2121
</td>
22-
<td>{{ warns.description|convert_markdown(heading_level, html_id) }}</td>
22+
<td>
23+
<div class="doc-md-description">
24+
{{ warns.description|convert_markdown(heading_level, html_id) }}
25+
</div>
26+
</td>
2327
</tr>
2428
{% endfor %}
2529
</tbody>
@@ -37,7 +41,9 @@
3741
{% endwith %}
3842
–
3943
{% endif %}
40-
{{ warns.description|convert_markdown(heading_level, html_id) }}
44+
<div class="doc-md-description">
45+
{{ warns.description|convert_markdown(heading_level, html_id) }}
46+
</div>
4147
</li>
4248
{% endfor %}
4349
</ul>
@@ -62,7 +68,9 @@
6268
</span>
6369
</td>
6470
<td class="doc-warns-details">
65-
{{ warns.description|convert_markdown(heading_level, html_id) }}
71+
<div class="doc-md-description">
72+
{{ warns.description|convert_markdown(heading_level, html_id) }}
73+
</div>
6674
</td>
6775
</tr>
6876
{% endfor %}

‎src/mkdocstrings_handlers/python/templates/material/_base/docstring/yields.html

+12-3
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,11 @@
2222
{% endwith %}
2323
{% endif %}
2424
</td>
25-
<td>{{ yields.description|convert_markdown(heading_level, html_id) }}</td>
25+
<td>
26+
<div class="doc-md-description">
27+
{{ yields.description|convert_markdown(heading_level, html_id) }}
28+
</div>
29+
</td>
2630
</tr>
2731
{% endfor %}
2832
</tbody>
@@ -42,7 +46,10 @@
4246
{% if yields.name %}){% endif %}
4347
{% endwith %}
4448
{% endif %}
45-
– {{ yields.description|convert_markdown(heading_level, html_id) }}
49+
–
50+
<div class="doc-md-description">
51+
{{ yields.description|convert_markdown(heading_level, html_id) }}
52+
</div>
4653
</li>
4754
{% endfor %}
4855
</ul>
@@ -71,7 +78,9 @@
7178
{% endif %}
7279
</td>
7380
<td class="doc-yields-details">
74-
{{ yields.description|convert_markdown(heading_level, html_id) }}
81+
<div class="doc-md-description">
82+
{{ yields.description|convert_markdown(heading_level, html_id) }}
83+
</div>
7584
{% if yields.name and yields.annotation %}
7685
<p>
7786
<span class="doc-yields-annotation">

‎src/mkdocstrings_handlers/python/templates/material/style.css

+6-10
Original file line numberDiff line numberDiff line change
@@ -8,10 +8,10 @@ h5.doc-heading {
88
word-break: normal !important;
99
}
1010

11-
/* For pieces of Markdown rendered in table cells. */
12-
.doc-contents td p {
13-
margin-top: 0 !important;
14-
margin-bottom: 0 !important;
11+
/* No line break before first paragraph of descriptions. */
12+
.doc-md-description,
13+
.doc-md-description>p:first-child {
14+
display: inline;
1515
}
1616

1717
/* Max width for docstring sections tables. */
@@ -20,16 +20,12 @@ h5.doc-heading {
2020
display: table !important;
2121
width: 100%;
2222
}
23+
2324
.doc .md-typeset__table tr {
2425
display: table-row;
2526
}
2627

27-
/* Avoid line breaks in rendered fields. */
28-
.field-body p {
29-
display: inline;
30-
}
31-
3228
/* Defaults in Spacy table style. */
3329
.doc-param-default {
3430
float: right;
35-
}
31+
}

0 commit comments

Comments
 (0)