Skip to content

Commit d5337af

Browse files
pawamoypawamoy
committed
feat: Add support for new Griffe docstring sections: modules, classes, and functions (methods)
1 parent d789160 commit d5337af

File tree

17 files changed

+504
-59
lines changed

17 files changed

+504
-59
lines changed

‎docs/usage/configuration/docstrings.md

+189
Original file line numberDiff line numberDiff line change
@@ -449,6 +449,195 @@ class Class:
449449
////
450450
///
451451

452+
## `show_docstring_functions`
453+
454+
- **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }**
455+
<!-- - **:octicons-project-template-24: Template :material-null:** (N/A) -->
456+
457+
Whether to render the "Functions" or "Methods" sections of docstrings.
458+
459+
```yaml title="in mkdocs.yml (global configuration)"
460+
plugins:
461+
- mkdocstrings:
462+
handlers:
463+
python:
464+
options:
465+
show_docstring_functions: true
466+
```
467+
468+
```md title="or in docs/some_page.md (local configuration)"
469+
::: path.to.module
470+
options:
471+
show_docstring_functions: false
472+
```
473+
474+
```python
475+
"""Summary.
476+
477+
Functions:
478+
foo: Some function.
479+
"""
480+
481+
482+
def foo():
483+
...
484+
485+
486+
class Class:
487+
"""Summary.
488+
489+
Methods:
490+
bar: Some method.
491+
"""
492+
493+
def bar(self):
494+
...
495+
```
496+
497+
/// admonition | Preview
498+
type: preview
499+
500+
//// tab | With functions
501+
<h2>module</h2>
502+
<p>Summary.</p>
503+
<p><b>Functions:</b></p>
504+
505+
**Name** | **Description**
506+
-------- | ---------------
507+
`foo` | Some function.
508+
509+
<h3><code>Class</code></h3>
510+
<p>Summary.</p>
511+
<p><b>Methods:</b></p>
512+
513+
**Name** | **Description**
514+
-------- | ---------------
515+
`bar` | Some method.
516+
////
517+
518+
//// tab | Without functions
519+
<h2>module</h2>
520+
<p>Summary.</p>
521+
<h3><code>Class</code></h3>
522+
<p>Summary.</p>
523+
////
524+
///
525+
526+
527+
## `show_docstring_classes`
528+
529+
- **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }**
530+
<!-- - **:octicons-project-template-24: Template :material-null:** (N/A) -->
531+
532+
Whether to render the "Classes" sections of docstrings.
533+
534+
```yaml title="in mkdocs.yml (global configuration)"
535+
plugins:
536+
- mkdocstrings:
537+
handlers:
538+
python:
539+
options:
540+
show_docstring_classes: true
541+
```
542+
543+
```md title="or in docs/some_page.md (local configuration)"
544+
::: path.to.module
545+
options:
546+
show_docstring_classes: false
547+
```
548+
549+
```python
550+
"""Summary.
551+
552+
Classes:
553+
Class: Some class.
554+
"""
555+
556+
557+
class Class:
558+
"""Summary."""
559+
```
560+
561+
/// admonition | Preview
562+
type: preview
563+
564+
//// tab | With classes
565+
<h2>module</h2>
566+
<p>Summary.</p>
567+
<p><b>Classes:</b></p>
568+
569+
**Name** | **Description**
570+
-------- | ---------------
571+
`Class` | Some class.
572+
573+
<h3><code>Class</code></h3>
574+
<p>Summary.</p>
575+
////
576+
577+
//// tab | Without classes
578+
<h2>module</h2>
579+
<p>Summary.</p>
580+
<h3><code>Class</code></h3>
581+
<p>Summary.</p>
582+
////
583+
///
584+
585+
## `show_docstring_modules`
586+
587+
- **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }**
588+
<!-- - **:octicons-project-template-24: Template :material-null:** (N/A) -->
589+
590+
Whether to render the "Modules" sections of docstrings.
591+
592+
```yaml title="in mkdocs.yml (global configuration)"
593+
plugins:
594+
- mkdocstrings:
595+
handlers:
596+
python:
597+
options:
598+
show_docstring_modules: true
599+
```
600+
601+
```md title="or in docs/some_page.md (local configuration)"
602+
::: path.to.module
603+
options:
604+
show_docstring_modules: false
605+
```
606+
607+
```tree
608+
module/
609+
__init__.py
610+
submodule.py
611+
```
612+
613+
```python title="module/__init__.py"
614+
"""Summary.
615+
616+
Modules:
617+
submodule: Some module.
618+
"""
619+
```
620+
621+
/// admonition | Preview
622+
type: preview
623+
624+
//// tab | With modules
625+
<h2>module</h2>
626+
<p>Summary.</p>
627+
<p><b>Modules:</b></p>
628+
629+
**Name** | **Description**
630+
----------- | ---------------
631+
`submodule` | Some module.
632+
633+
////
634+
635+
//// tab | Without modules
636+
<h2>module</h2>
637+
<p>Summary.</p>
638+
////
639+
///
640+
452641
## `show_docstring_description`
453642

454643
- **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }**

‎docs/usage/customization.md

+11-1
Original file line numberDiff line numberDiff line change
@@ -151,7 +151,17 @@ Available context:
151151

152152
#### Docstring sections
153153

154-
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`:
154+
In `docstring/attributes.html`,
155+
`docstring/functions.html`,
156+
`docstring/classes.html`,
157+
`docstring/modules.html`,
158+
`docstring/other_parameters.html`,
159+
`docstring/parameters.html`,
160+
`docstring/raises.html`,
161+
`docstring/receives.html`,
162+
`docstring/returns.html`,
163+
`docstring/warns.html`,
164+
and `docstring/yields.html`:
155165

156166
- `table_style`: The section as a table.
157167
- `list_style`: The section as a list.

‎src/mkdocstrings_handlers/python/handler.py

+6
Original file line numberDiff line numberDiff line change
@@ -84,6 +84,9 @@ class PythonHandler(BaseHandler):
8484
"line_length": 60,
8585
"merge_init_into_class": False,
8686
"show_docstring_attributes": True,
87+
"show_docstring_functions": True,
88+
"show_docstring_classes": True,
89+
"show_docstring_modules": True,
8790
"show_docstring_description": True,
8891
"show_docstring_examples": True,
8992
"show_docstring_other_parameters": True,
@@ -157,6 +160,9 @@ class PythonHandler(BaseHandler):
157160
merge_init_into_class (bool): Whether to merge the `__init__` method into the class' signature and docstring. Default: `False`.
158161
show_if_no_docstring (bool): Show the object heading even if it has no docstring or children with docstrings. Default: `False`.
159162
show_docstring_attributes (bool): Whether to display the "Attributes" section in the object's docstring. Default: `True`.
163+
show_docstring_functions (bool): Whether to display the "Functions" or "Methods" sections in the object's docstring. Default: `True`.
164+
show_docstring_classes (bool): Whether to display the "Classes" section in the object's docstring. Default: `True`.
165+
show_docstring_modules (bool): Whether to display the "Modules" section in the object's docstring. Default: `True`.
160166
show_docstring_description (bool): Whether to display the textual block (including admonitions) in the object's docstring. Default: `True`.
161167
show_docstring_examples (bool): Whether to display the "Examples" section in the object's docstring. Default: `True`.
162168
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-1
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
{{ log.debug("Rendering " + attribute.path) }}
22

33
<div class="doc doc-object doc-attribute">
4-
{% with html_id = attribute.path %}
4+
{% with obj = attribute, html_id = attribute.path %}
55

66
{% if root %}
77
{% set show_full_path = config.show_root_full_path %}

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

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
{{ log.debug("Rendering " + class.path) }}
22

33
<div class="doc doc-object doc-class">
4-
{% with html_id = class.path %}
4+
{% with obj = class, html_id = class.path %}
55

66
{% if root %}
77
{% set show_full_path = config.show_root_full_path %}

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

+6
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,12 @@
55
{{ section.value|convert_markdown(heading_level, html_id) }}
66
{% elif config.show_docstring_attributes and section.kind.value == "attributes" %}
77
{% include "docstring/attributes.html" with context %}
8+
{% elif config.show_docstring_functions and section.kind.value == "functions" %}
9+
{% include "docstring/functions.html" with context %}
10+
{% elif config.show_docstring_classes and section.kind.value == "classes" %}
11+
{% include "docstring/classes.html" with context %}
12+
{% elif config.show_docstring_modules and section.kind.value == "modules" %}
13+
{% include "docstring/modules.html" with context %}
814
{% elif config.show_docstring_parameters and section.kind.value == "parameters" %}
915
{% include "docstring/parameters.html" with context %}
1016
{% elif config.show_docstring_other_parameters and section.kind.value == "other parameters" %}

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

+67
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
{{ log.debug("Rendering classes section") }}
2+
3+
{% import "language.html" as lang with context %}
4+
5+
{% if config.docstring_section_style == "table" %}
6+
{% block table_style %}
7+
<p><strong>{{ section.title or lang.t("Classes:") }}</strong></p>
8+
<table>
9+
<thead>
10+
<tr>
11+
<th>{{ lang.t("Name") }}</th>
12+
<th>{{ lang.t("Description") }}</th>
13+
</tr>
14+
</thead>
15+
<tbody>
16+
{% for class in section.value %}
17+
<tr>
18+
<td><code>{{ class.name }}</code></td>
19+
<td>
20+
<div class="doc-md-description">
21+
{{ class.description|convert_markdown(heading_level, html_id) }}
22+
</div>
23+
</td>
24+
</tr>
25+
{% endfor %}
26+
</tbody>
27+
</table>
28+
{% endblock table_style %}
29+
{% elif config.docstring_section_style == "list" %}
30+
{% block list_style %}
31+
<p>{{ section.title or lang.t("Classes:") }}</p>
32+
<ul>
33+
{% for class in section.value %}
34+
<li class="field-body">
35+
<b>{{ class.name }}</b>
36+
–
37+
<div class="doc-md-description">
38+
{{ class.description|convert_markdown(heading_level, html_id) }}
39+
</div>
40+
</li>
41+
{% endfor %}
42+
</ul>
43+
{% endblock list_style %}
44+
{% elif config.docstring_section_style == "spacy" %}
45+
{% block spacy_style %}
46+
<table>
47+
<thead>
48+
<tr>
49+
<th><b>{{ (section.title or lang.t("CLASS")).rstrip(":").upper() }}</b></th>
50+
<th><b>{{ lang.t("DESCRIPTION") }}</b></th>
51+
</tr>
52+
</thead>
53+
<tbody>
54+
{% for class in section.value %}
55+
<tr>
56+
<td><code>{{ class.name }}</code></td>
57+
<td class="doc-class-details">
58+
<div class="doc-md-description">
59+
{{ class.description|convert_markdown(heading_level, html_id) }}
60+
</div>
61+
</td>
62+
</tr>
63+
{% endfor %}
64+
</tbody>
65+
</table>
66+
{% endblock spacy_style %}
67+
{% endif %}

0 commit comments

Comments
 (0)