feat: Add support for new Griffe docstring sections: modules, classes, and functions (methods)

Author: pawamoy

docs/usage/configuration/docstrings.md

@@ -449,6 +449,195 @@ class Class:
 ////
 ///
 
+## `show_docstring_functions`
+
+- **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }**
+<!-- - **:octicons-project-template-24: Template :material-null:** (N/A) -->
+
+Whether to render the "Functions" or "Methods" sections of docstrings.
+
+```yaml title="in mkdocs.yml (global configuration)"
+plugins:
+- mkdocstrings:
+    handlers:
+      python:
+        options:
+          show_docstring_functions: true
+```
+
+```md title="or in docs/some_page.md (local configuration)"
+::: path.to.module
+    options:
+      show_docstring_functions: false
+```
+
+```python
+"""Summary.
+
+Functions:
+    foo: Some function.
+"""
+
+
+def foo():
+    ...
+
+
+class Class:
+    """Summary.
+
+    Methods:
+        bar: Some method.
+    """
+
+    def bar(self):
+        ...
+```
+
+/// admonition | Preview
+    type: preview
+
+//// tab | With functions
+<h2>module</h2>
+<p>Summary.</p>
+<p><b>Functions:</b></p>
+
+**Name** | **Description**
+-------- | ---------------
+`foo`    | Some function.
+
+<h3><code>Class</code></h3>
+<p>Summary.</p>
+<p><b>Methods:</b></p>
+
+**Name** | **Description**
+-------- | ---------------
+`bar`    | Some method.
+////
+
+//// tab | Without functions
+<h2>module</h2>
+<p>Summary.</p>
+<h3><code>Class</code></h3>
+<p>Summary.</p>
+////
+///
+
+
+## `show_docstring_classes`
+
+- **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }**
+<!-- - **:octicons-project-template-24: Template :material-null:** (N/A) -->
+
+Whether to render the "Classes" sections of docstrings.
+
+```yaml title="in mkdocs.yml (global configuration)"
+plugins:
+- mkdocstrings:
+    handlers:
+      python:
+        options:
+          show_docstring_classes: true
+```
+
+```md title="or in docs/some_page.md (local configuration)"
+::: path.to.module
+    options:
+      show_docstring_classes: false
+```
+
+```python
+"""Summary.
+
+Classes:
+    Class: Some class.
+"""
+
+
+class Class:
+    """Summary."""
+```
+
+/// admonition | Preview
+    type: preview
+
+//// tab | With classes
+<h2>module</h2>
+<p>Summary.</p>
+<p><b>Classes:</b></p>
+
+**Name** | **Description**
+-------- | ---------------
+`Class`  | Some class.
+
+<h3><code>Class</code></h3>
+<p>Summary.</p>
+////
+
+//// tab | Without classes
+<h2>module</h2>
+<p>Summary.</p>
+<h3><code>Class</code></h3>
+<p>Summary.</p>
+////
+///
+
+## `show_docstring_modules`
+
+- **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }**
+<!-- - **:octicons-project-template-24: Template :material-null:** (N/A) -->
+
+Whether to render the "Modules" sections of docstrings.
+
+```yaml title="in mkdocs.yml (global configuration)"
+plugins:
+- mkdocstrings:
+    handlers:
+      python:
+        options:
+          show_docstring_modules: true
+```
+
+```md title="or in docs/some_page.md (local configuration)"
+::: path.to.module
+    options:
+      show_docstring_modules: false
+```
+
+```tree
+module/
+    __init__.py
+    submodule.py
+```
+
+```python title="module/__init__.py"
+"""Summary.
+
+Modules:
+    submodule: Some module.
+"""
+```
+
+/// admonition | Preview
+    type: preview
+
+//// tab | With modules
+<h2>module</h2>
+<p>Summary.</p>
+<p><b>Modules:</b></p>
+
+**Name**    | **Description**
+----------- | ---------------
+`submodule` | Some module.
+
+////
+
+//// tab | Without modules
+<h2>module</h2>
+<p>Summary.</p>
+////
+///
+
 ## `show_docstring_description`
 
 - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }**

docs/usage/customization.md

@@ -151,7 +151,17 @@ Available context:
 
 #### Docstring sections
 
-In `docstring/attributes.html`, `docstring/other_parameters.html`, `docstring/parameters.html`, `docstring/raises.html`, `docstring/receives.html`, `docstring/returns.html`, `docstring/warns.html`, and `docstring/yields.html`:
+In `docstring/attributes.html`,
+`docstring/functions.html`, 
+`docstring/classes.html`, 
+`docstring/modules.html`, 
+`docstring/other_parameters.html`,
+`docstring/parameters.html`,
+`docstring/raises.html`,
+`docstring/receives.html`,
+`docstring/returns.html`,
+`docstring/warns.html`,
+and `docstring/yields.html`:
 
 - `table_style`: The section as a table.
 - `list_style`: The section as a list.

src/mkdocstrings_handlers/python/handler.py

@@ -84,6 +84,9 @@ class PythonHandler(BaseHandler):
         "line_length": 60,
         "merge_init_into_class": False,
         "show_docstring_attributes": True,
+        "show_docstring_functions": True,
+        "show_docstring_classes": True,
+        "show_docstring_modules": True,
         "show_docstring_description": True,
         "show_docstring_examples": True,
         "show_docstring_other_parameters": True,
@@ -157,6 +160,9 @@ class PythonHandler(BaseHandler):
         merge_init_into_class (bool): Whether to merge the `__init__` method into the class' signature and docstring. Default: `False`.
         show_if_no_docstring (bool): Show the object heading even if it has no docstring or children with docstrings. Default: `False`.
         show_docstring_attributes (bool): Whether to display the "Attributes" section in the object's docstring. Default: `True`.
+        show_docstring_functions (bool): Whether to display the "Functions" or "Methods" sections in the object's docstring. Default: `True`.
+        show_docstring_classes (bool): Whether to display the "Classes" section in the object's docstring. Default: `True`.
+        show_docstring_modules (bool): Whether to display the "Modules" section in the object's docstring. Default: `True`.
         show_docstring_description (bool): Whether to display the textual block (including admonitions) in the object's docstring. Default: `True`.
         show_docstring_examples (bool): Whether to display the "Examples" section in the object's docstring. Default: `True`.
         show_docstring_other_parameters (bool): Whether to display the "Other Parameters" section in the object's docstring. Default: `True`.

src/mkdocstrings_handlers/python/templates/material/_base/attribute.html

@@ -1,7 +1,7 @@
 {{ log.debug("Rendering " + attribute.path) }}
 
 <div class="doc doc-object doc-attribute">
-{% with html_id = attribute.path %}
+{% with obj = attribute, html_id = attribute.path %}
 
   {% if root %}
     {% set show_full_path = config.show_root_full_path %}

src/mkdocstrings_handlers/python/templates/material/_base/class.html

@@ -1,7 +1,7 @@
 {{ log.debug("Rendering " + class.path) }}
 
 <div class="doc doc-object doc-class">
-{% with html_id = class.path %}
+{% with obj = class, html_id = class.path %}
 
   {% if root %}
     {% set show_full_path = config.show_root_full_path %}

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

@@ -5,6 +5,12 @@
       {{ section.value|convert_markdown(heading_level, html_id) }}
     {% elif config.show_docstring_attributes and section.kind.value == "attributes" %}
       {% include "docstring/attributes.html" with context %}
+    {% elif config.show_docstring_functions and section.kind.value == "functions" %}
+      {% include "docstring/functions.html" with context %}
+    {% elif config.show_docstring_classes and section.kind.value == "classes" %}
+      {% include "docstring/classes.html" with context %}
+    {% elif config.show_docstring_modules and section.kind.value == "modules" %}
+      {% include "docstring/modules.html" with context %}
     {% elif config.show_docstring_parameters and section.kind.value == "parameters" %}
       {% include "docstring/parameters.html" with context %}
     {% elif config.show_docstring_other_parameters and section.kind.value == "other parameters" %}

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

@@ -0,0 +1,67 @@
+{{ log.debug("Rendering classes section") }}
+
+{% import "language.html" as lang with context %}
+
+{% if config.docstring_section_style == "table" %}
+  {% block table_style %}
+  <p><strong>{{ section.title or lang.t("Classes:") }}</strong></p>
+  <table>
+    <thead>
+      <tr>
+        <th>{{ lang.t("Name") }}</th>
+        <th>{{ lang.t("Description") }}</th>
+      </tr>
+    </thead>
+    <tbody>
+      {% for class in section.value %}
+        <tr>
+          <td><code>{{ class.name }}</code></td>
+          <td>
+            <div class="doc-md-description">
+              {{ class.description|convert_markdown(heading_level, html_id) }}
+            </div>
+          </td>
+        </tr>
+      {% endfor %}
+    </tbody>
+  </table>
+  {% endblock table_style %}
+{% elif config.docstring_section_style == "list" %}
+  {% block list_style %}
+  <p>{{ section.title or lang.t("Classes:") }}</p>
+  <ul>
+    {% for class in section.value %}
+      <li class="field-body">
+        <b>{{ class.name }}</b>
+        –
+        <div class="doc-md-description">
+          {{ class.description|convert_markdown(heading_level, html_id) }}
+        </div>
+      </li>
+    {% endfor %}
+  </ul>
+  {% endblock list_style %}
+{% elif config.docstring_section_style == "spacy" %}
+  {% block spacy_style %}
+  <table>
+    <thead>
+      <tr>
+        <th><b>{{ (section.title or lang.t("CLASS")).rstrip(":").upper() }}</b></th>
+        <th><b>{{ lang.t("DESCRIPTION") }}</b></th>
+      </tr>
+    </thead>
+    <tbody>
+      {% for class in section.value %}
+        <tr>
+          <td><code>{{ class.name }}</code></td>
+          <td class="doc-class-details">
+            <div class="doc-md-description">
+              {{ class.description|convert_markdown(heading_level, html_id) }}
+            </div>
+          </td>
+        </tr>
+      {% endfor %}
+    </tbody>
+  </table>
+  {% endblock spacy_style %}
+{% endif %}