8000 feat: Add show options for docstrings · FasterSpeeding/python@a6c55fb · GitHub
[go: up one dir, main page]
Skip to content

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit a6c55fb

Browse files
thatlittleboythatlittleboy
authored
feat: Add show options for docstrings
Issue mkdocstrings/mkdocstrings#466: mkdocstrings/mkdocstrings#466 PR mkdocstrings#56: mkdocstrings#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)
0