Skip to content

Commit a6c55fb

Browse files
thatlittleboythatlittleboy
authored
feat: Add show options for docstrings
Issue mkdocstrings/mkdocstrings#466: mkdocstrings/mkdocstrings#466 PR #56: #56
1 parent f5ea6fd commit a6c55fb

File tree

3 files changed

+94
-14
lines changed

3 files changed

+94
-14
lines changed

‎docs/schema.json

Lines changed: 61 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -140,8 +140,68 @@
140140
"type": "boolean",
141141
"default": false
142142
},
143+
"show_docstring_attributes": {
144+
"title": "Whether to display the \"Attributes\" section in the object's docstring.",
145+
"markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options",
146+
"type": "boolean",
147+
"default": true
148+
},
149+
"show_docstring_description": {
150+
"title": "Whether to display the textual block (including admonitions) in the object's docstring.",
151+
"markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options",
152+
"type": "boolean",
153+
"default": true
154+
},
155+
"show_docstring_examples": {
156+
"title": "Whether to display the \"Examples\" section in the object's docstring.",
157+
"markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options",
158+
"type": "boolean",
159+
"default": true
160+
},
161+
"show_docstring_other_parameters": {
162+
"title": "Whether to display the \"Other Parameters\" section in the object's docstring.",
163+
"markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options",
164+
"type": "boolean",
165+
"default": true
166+
},
167+
"show_docstring_parameters": {
168+
"title": "Whether to display the \"Parameters\" section in the object's docstring.",
169+
"markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options",
170+
"type": "boolean",
171+
"default": true
172+
},
173+
"show_docstring_raises": {
174+
"title": "Whether to display the \"Raises\" section in the object's docstring.",
175+
"markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options",
176+
"type": "boolean",
177+
"default": true
178+
},
179+
"show_docstring_receives": {
180+
"title": "Whether to display the \"Receives\" section in the object's docstring.",
181+
"markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options",
182+
"type": "boolean",
183+
"default": true
184+
},
185+
"show_docstring_returns": {
186+
"title": "Whether to display the \"Returns\" section in the object's docstring.",
187+
"markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options",
188+
"type": "boolean",
189+
"default": true
190+
},
191+
"show_docstring_warns": {
192+
"title": "Whether to display the \"Warns\" section in the object's docstring.",
193+
"markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options",
194+
"type": "boolean",
195+
"default": true
196+
},
197+
"show_docstring_yields": {
198+
"title": "Whether to display the \"Yields\" section in the object's docstring.",
199+
"markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options",
200+
"type": "boolean",
201+
"default": true
202+
},
143203
"show_source": {
144-
"title": "Show the source code of this object..",
204+
"title": "Show the source code of this object.",
145205
"markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options",
146206
"type": "boolean",
147207
"default": true

‎src/mkdocstrings_handlers/python/handler.py

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -79,6 +79,16 @@ class PythonHandler(BaseHandler):
7979
"separate_signature": False,
8080
"line_length": 60,
8181
"merge_init_into_class": False,
82+
"show_docstring_attributes": True,
83+
"show_docstring_description": True,
84+
"show_docstring_examples": True,
85+
"show_docstring_other_parameters": True,
86+
"show_docstring_parameters": True,
87+
"show_docstring_raises": True,
88+
"show_docstring_receives": True,
89+
"show_docstring_returns": True,
90+
"show_docstring_warns": True,
91+
"show_docstring_yields": True,
8292
"show_source": True,
8393
"show_bases": True,
8494
"show_submodules": False,
@@ -119,6 +129,16 @@ class PythonHandler(BaseHandler):
119129
line_length (int): Maximum line length when formatting code/signatures. Default: `60`.
120130
merge_init_into_class (bool): Whether to merge the `__init__` method into the class' signature and docstring. Default: `False`.
121131
show_if_no_docstring (bool): Show the object heading even if it has no docstring or children with docstrings. Default: `False`.
132+
show_docstring_attributes (bool): Whether to display the "Attributes" section in the object's docstring. Default: `True`.
133+
show_docstring_description (bool): Whether to display the textual block (including admonitions) in the object's docstring. Default: `True`.
134+
show_docstring_examples (bool): Whether to display the "Examples" section in the object's docstring. Default: `True`.
135+
show_docstring_other_parameters (bool): Whether to display the "Other Parameters" section in the object's docstring. Default: `True`.
136+
show_docstring_parameters (bool): Whether to display the "Parameters" section in the object's docstring. Default: `True`.
137+
show_docstring_raises (bool): Whether to display the "Raises" section in the object's docstring. Default: `True`.
138+
show_docstring_receives (bool): Whether to display the "Receives" section in the object's docstring. Default: `True`.
139+
show_docstring_returns (bool): Whether to display the "Returns" section in the object's docstring. Default: `True`.
140+
show_docstring_warns (bool): Whether to display the "Warns" section in the object's docstring. Default: `True`.
141+
show_docstring_yields (bool): Whether to display the "Yields" section in the object's docstring. Default: `True`.
122142
123143
Attributes: Signatures/annotations options:
124144
annotations_path (str): The verbosity for annotations path: `brief` (recommended), or `source` (as written in the source). Default: `"brief"`.

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

Lines changed: 13 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,27 @@
11
{% if docstring_sections %}
22
{{ log.debug("Rendering docstring") }}
33
{% for section in docstring_sections %}
4-
{% if section.kind.value == "text" %}
4+
{% if config.show_docstring_description and section.kind.value == "text" %}
55
{{ section.value|convert_markdown(heading_level, html_id) }}
6-
{% elif section.kind.value == "attributes" %}
6+
{% elif config.show_docstring_attributes and section.kind.value == "attributes" %}
77
{% include "docstring/attributes.html" with context %}
8-
{% elif section.kind.value == "parameters" %}
8+
{% elif config.show_docstring_parameters and section.kind.value == "parameters" %}
99
{% include "docstring/parameters.html" with context %}
10-
{% elif section.kind.value == "other parameters" %}
10+
{% elif config.show_docstring_other_parameters and section.kind.value == "other parameters" %}
1111
{% include "docstring/other_parameters.html" with context %}
12-
{% elif section.kind.value == "raises" %}
12+
{% elif config.show_docstring_raises and section.kind.value == "raises" %}
1313
{% include "docstring/raises.html" with context %}
14-
{% elif section.kind.value == "warns" %}
15-
{% include "docstring/warns.html" with context %}
16-
{% elif section.kind.value == "yields" %}
14+
{% elif config.show_docstring_warns and section.kind.value == "warns" %}
15+
{% include "docstring/warns.html" with context %}
16+
{% elif config.show_docstring_yields and section.kind.value == "yields" %}
1717
{% include "docstring/yields.html" with context %}
18-
{% elif section.kind.value == "receives" %}
19-
{% include "docstring/receives.html" with context %}
20-
{% elif section.kind.value == "returns" %}
18+
{% elif config.show_docstring_receives and section.kind.value == "receives" %}
19+
{% include "docstring/receives.html" with context %}
20+
{% elif config.show_docstring_returns and section.kind.value == "returns" %}
2121
{% include "docstring/returns.html" with context %}
22-
{% elif section.kind.value == "examples" %}
22+
{% elif config.show_docstring_examples and section.kind.value == "examples" %}
2323
{% include "docstring/examples.html" with context %}
24-
{% elif section.kind.value == "admonition" %}
24+
{% elif config.show_docstring_description and section.kind.value == "admonition" %}
2525
{% include "docstring/admonition.html" with context %}
2626
{% endif %}
2727
{% endfor %}

0 commit comments

Comments
 (0)