fix: Fix templates for named docstring elements

mkdocstrings · Dec 20, 2021 · 47868a1 · 47868a1
1 parent 29b174c
commit 47868a1
Show file tree

Hide file tree

Showing 5 changed files with 102 additions and 60 deletions.
diff --git a/src/mkdocstrings/templates/python/material/_base/docstring/raises.html b/src/mkdocstrings/templates/python/material/_base/docstring/raises.html
@@ -49,19 +49,15 @@
     <tbody>
       {% for raises in section.value %}
         <tr>
-          <td><code>{{ raises.name }}</code></td>
+          <td>
+            <span class="doc-raises-annotation">
+              {% with expression = raises.annotation %}
+                <code>{% include "expression.html" with context %}</code>
+              {% endwith %}
+            </span>
+          </td>
           <td class="doc-raises-details">
             {{ raises.description|convert_markdown(heading_level, html_id) }}
-            <p>
-              {% if raises.annotation %}
-                <span class="doc-raises-annotation">
-                  <b>TYPE:</b>
-                  {% with expression = raises.annotation %}
-                    <code>{% include "expression.html" with context %}</code>
-                  {% endwith %}
-                </span>
-              {% endif %}
-            </p>
           </td>
         </tr>
       {% endfor %}

diff --git a/src/mkdocstrings/templates/python/material/_base/docstring/receives.html b/src/mkdocstrings/templates/python/material/_base/docstring/receives.html
@@ -1,16 +1,19 @@
 {{ log.debug() }}
 {% if config.docstring_section_style == "table" %}
+  {% set name_column = section.value|selectattr("name")|any %}
   <p><strong>{{ section.title or "Receives:" }}</strong></p>
   <table>
     <thead>
       <tr>
+        {% if name_column %}<th>Name</th>{% endif %}
         <th>Type</th>
         <th>Description</th>
       </tr>
     </thead>
     <tbody>
-      <tr>
-        {% with receives = section.value %}
+      {% for receives in section.value %}
+        <tr>
+          {% if name_column %}<td>{% if receives.name %}<code>{{ receives.name }}</code>{% endif %}</td>{% endif %}
           <td>
             {% if receives.annotation %}
               {% with expression = receives.annotation %}
@@ -19,24 +22,26 @@
             {% endif %}
           </td>
           <td>{{ receives.description|convert_markdown(heading_level, html_id) }}</td>
-        {% endwith %}
-      </tr>
+        </tr>
+      {% endfor %}
     </tbody>
   </table>
 {% elif config.docstring_section_style == "list" %}
   <p>{{ section.title or "Receives:" }}</p>
   <ul>
-    {% with receives = section.value %}
+    {% for receives in section.value %}
       <li class="field-body">
+        {% if receives.name %}<b>{{ receives.name }}</b>{% endif %}
         {% if receives.annotation %}
           {% with expression = receives.annotation %}
+            {% if receives.name %}({% endif %}
             <code>{% include "expression.html" with context %}</code>
+            {% if receives.name %}){% endif %}
           {% endwith %}
-          –
         {% endif %}
-        {{ receives.description|convert_markdown(heading_level, html_id) }}
+        – {{ receives.description|convert_markdown(heading_level, html_id) }}
       </li>
-    {% endwith %}
+    {% endfor %}
   </ul>
 {% elif config.docstring_section_style == "spacy" %}
   <table>
@@ -47,21 +52,31 @@
       </tr>
     </thead>
     <tbody>
-      {% for receive in section.value %}
+      {% for receives in section.value %}
         <tr>
-          <td><code>{{ receive.name }}</code></td>
-          <td class="doc-receive-details">
-            {{ receive.description|convert_markdown(heading_level, html_id) }}
-            <p>
-              {% if receive.annotation %}
-                <span class="doc-receive-annotation">
+          <td>
+            {% if receives.name %}
+              <code>{{ receives.name }}</code>
+            {% elif receives.annotation %}
+              <span class="doc-receives-annotation">
+                {% with expression = receives.annotation %}
+                  <code>{% include "expression.html" with context %}</code>
+                {% endwith %}
+              </span>
+            {% endif %}
+          </td>
+          <td class="doc-receives-details">
+            {{ receives.description|convert_markdown(heading_level, html_id) }}
+            {% if receives.name and receives.annotation %}
+              <p>
+                <span class="doc-receives-annotation">
                   <b>TYPE:</b>
-                  {% with expression = receive.annotation %}
+                  {% with expression = receives.annotation %}
                     <code>{% include "expression.html" with context %}</code>
                   {% endwith %}
                 </span>
-              {% endif %}
-            </p>
+              </p>
+            {% endif %}
           </td>
         </tr>
       {% endfor %}

diff --git a/src/mkdocstrings/templates/python/material/_base/docstring/returns.html b/src/mkdocstrings/templates/python/material/_base/docstring/returns.html
@@ -45,18 +45,38 @@
   </ul>
 {% elif config.docstring_section_style == "spacy" %}
   <table>
+    <thead>
+      <tr>
+        <th><b>RETURNS</b></th>
+        <th><b>DESCRIPTION</b></th>
+      </tr>
+    </thead>
     <tbody>
-      <tr><td><b>RETURNS</b></td></tr>
       {% for returns in section.value %}
         <tr>
+          <td>
+            {% if returns.name %}
+              <code>{{ returns.name }}</code>
+            {% elif returns.annotation %}
+              <span class="doc-returns-annotation">
+                {% with expression = returns.annotation %}
+                  <code>{% include "expression.html" with context %}</code>
+                {% endwith %}
+              </span>
+            {% endif %}
+          </td>
           <td class="doc-returns-details">
             {{ returns.description|convert_markdown(heading_level, html_id) }}
-            <p>
-              <b>TYPE:</b>
-              {% with expression = returns.annotation %}
-                <code>{% include "expression.html" with context %}</code>
-              {% endwith %}
-            </p>
+            {% if returns.name and returns.annotation %}
+              <p>
+                <span class="doc-returns-annotation">
+                  <b>TYPE:</b>
+                  {% with expression = returns.annotation %}
+                    <code>{% include "expression.html" with context %}</code>
+                  {% endwith %}
+                </span>
+              </p>
+            {% endif %}
           </td>
         </tr>
       {% endfor %}

diff --git a/src/mkdocstrings/templates/python/material/_base/docstring/warns.html b/src/mkdocstrings/templates/python/material/_base/docstring/warns.html
@@ -49,19 +49,15 @@
     <tbody>
       {% for warns in section.value %}
         <tr>
-          <td><code>{{ warns.name }}</code></td>
+          <td>
+            <span class="doc-warns-annotation">
+              {% with expression = warns.annotation %}
+                <code>{% include "expression.html" with context %}</code>
+              {% endwith %}
+            </span>
+          </td>
           <td class="doc-warns-details">
             {{ warns.description|convert_markdown(heading_level, html_id) }}
-            <p>
-              {% if warns.annotation %}
-                <span class="doc-warns-annotation">
-                  <b>TYPE:</b>
-                  {% with expression = warns.annotation %}
-                    <code>{% include "expression.html" with context %}</code>
-                  {% endwith %}
-                </span>
-              {% endif %}
-            </p>
           </td>
         </tr>
       {% endfor %}

diff --git a/src/mkdocstrings/templates/python/material/_base/docstring/yields.html b/src/mkdocstrings/templates/python/material/_base/docstring/yields.html
@@ -1,16 +1,19 @@
 {{ log.debug() }}
 {% if config.docstring_section_style == "table" %}
+  {% set name_column = section.value|selectattr("name")|any %}
   <p><strong>{{ section.title or "Yields:" }}</strong></p>
   <table>
     <thead>
       <tr>
+        {% if name_column %}<th>Name</th>{% endif %}
         <th>Type</th>
         <th>Description</th>
       </tr>
     </thead>
     <tbody>
-      <tr>
-        {% with yields = section.value %}
+      {% for yields in section.value %}
+        <tr>
+          {% if name_column %}<td>{% if yields.name %}<code>{{ yields.name }}</code>{% endif %}</td>{% endif %}
           <td>
             {% if yields.annotation %}
               {% with expression = yields.annotation %}
@@ -19,24 +22,26 @@
             {% endif %}
           </td>
           <td>{{ yields.description|convert_markdown(heading_level, html_id) }}</td>
-        {% endwith %}
-      </tr>
+        </tr>
+      {% endfor %}
     </tbody>
   </table>
 {% elif config.docstring_section_style == "list" %}
   <p>{{ section.title or "Yields:" }}</p>
   <ul>
-    {% with yields = section.value %}
+    {% for yields in section.value %}
       <li class="field-body">
+        {% if yields.name %}<b>{{ yields.name }}</b>{% endif %}
         {% if yields.annotation %}
           {% with expression = yields.annotation %}
+            {% if yields.name %}({% endif %}
             <code>{% include "expression.html" with context %}</code>
+            {% if yields.name %}){% endif %}
           {% endwith %}
-          –
         {% endif %}
-        {{ yields.description|convert_markdown(heading_level, html_id) }}
+        – {{ yields.description|convert_markdown(heading_level, html_id) }}
       </li>
-    {% endwith %}
+    {% endfor %}
   </ul>
 {% elif config.docstring_section_style == "spacy" %}
   <table>
@@ -49,19 +54,29 @@
     <tbody>
       {% for yields in section.value %}
         <tr>
-          <td><code>{{ yields.name }}</code></td>
+          <td>
+            {% if yields.name %}
+              <code>{{ yields.name }}</code>
+            {% elif yields.annotation %}
+              <span class="doc-yields-annotation">
+                {% with expression = yields.annotation %}
+                  <code>{% include "expression.html" with context %}</code>
+                {% endwith %}
+              </span>
+            {% endif %}
+          </td>
           <td class="doc-yields-details">
             {{ yields.description|convert_markdown(heading_level, html_id) }}
-            <p>
-              {% if yields.annotation %}
+            {% if yields.name and yields.annotation %}
+              <p>
                 <span class="doc-yields-annotation">
                   <b>TYPE:</b>
                   {% with expression = yields.annotation %}
                     <code>{% include "expression.html" with context %}</code>
                   {% endwith %}
                 </span>
-              {% endif %}
-            </p>
+              </p>
+            {% endif %}
           </td>
         </tr>
       {% endfor %}