Skip to content

Commit

Permalink
feat: Add show options for docstrings
Browse files Browse the repository at this point in the history 
Issue mkdocstrings/mkdocstrings#466: mkdocstrings/mkdocstrings#466
PR #56: #56
  • Loading branch information
@thatlittleboy
thatlittleboy authored Feb 3, 2023
1 parent f5ea6fd commit a6c55fb
Show file tree
Hide file tree
Showing 3 changed files with 94 additions and 14 deletions.
62 changes: 61 additions & 1 deletion docs/schema.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -140,8 +140,68 @@
"type": "boolean",
"default": false
},
"show_docstring_attributes": {
"title": "Whether to display the \"Attributes\" section in the object's docstring.",
"markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options",
"type": "boolean",
"default": true
},
"show_docstring_description": {
"title": "Whether to display the textual block (including admonitions) in the object's docstring.",
"markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options",
"type": "boolean",
"default": true
},
"show_docstring_examples": {
"title": "Whether to display the \"Examples\" section in the object's docstring.",
"markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options",
"type": "boolean",
"default": true
},
"show_docstring_other_parameters": {
"title": "Whether to display the \"Other Parameters\" section in the object's docstring.",
"markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options",
"type": "boolean",
"default": true
},
"show_docstring_parameters": {
"title": "Whether to display the \"Parameters\" section in the object's docstring.",
"markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options",
"type": "boolean",
"default": true
},
"show_docstring_raises": {
"title": "Whether to display the \"Raises\" section in the object's docstring.",
"markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options",
"type": "boolean",
"default": true
},
"show_docstring_receives": {
"title": "Whether to display the \"Receives\" section in the object's docstring.",
"markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options",
"type": "boolean",
"default": true
},
"show_docstring_returns": {
"title": "Whether to display the \"Returns\" section in the object's docstring.",
"markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options",
"type": "boolean",
"default": true
},
"show_docstring_warns": {
"title": "Whether to display the \"Warns\" section in the object's docstring.",
"markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options",
"type": "boolean",
"default": true
},
"show_docstring_yields": {
"title": "Whether to display the \"Yields\" section in the object's docstring.",
"markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options",
"type": "boolean",
"default": true
},
"show_source": {
"title": "Show the source code of this object..",
"title": "Show the source code of this object.",
"markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options",
"type": "boolean",
"default": true
Expand Down
20 changes: 20 additions & 0 deletions src/mkdocstrings_handlers/python/handler.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -79,6 +79,16 @@ class PythonHandler(BaseHandler):
"separate_signature": False,
"line_length": 60,
"merge_init_into_class": False,
"show_docstring_attributes": True,
"show_docstring_description": True,
"show_docstring_examples": True,
"show_docstring_other_parameters": True,
"show_docstring_parameters": True,
"show_docstring_raises": True,
"show_docstring_receives": True,
"show_docstring_returns": True,
"show_docstring_warns": True,
"show_docstring_yields": True,
"show_source": True,
"show_bases": True,
"show_submodules": False,
Expand Down Expand Up @@ -119,6 +129,16 @@ class PythonHandler(BaseHandler):
line_length (int): Maximum line length when formatting code/signatures. Default: `60`.
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_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`.
show_docstring_parameters (bool): Whether to display the "Parameters" section in the object's docstring. Default: `True`.
show_docstring_raises (bool): Whether to display the "Raises" section in the object's docstring. Default: `True`.
show_docstring_receives (bool): Whether to display the "Receives" section in the object's docstring. Default: `True`.
show_docstring_returns (bool): Whether to display the "Returns" section in the object's docstring. Default: `True`.
show_docstring_warns (bool): Whether to display the "Warns" section in the object's docstring. Default: `True`.
show_docstring_yields (bool): Whether to display the "Yields" section in the object's docstring. Default: `True`.
Attributes: Signatures/annotations options:
annotations_path (str): The verbosity for annotations path: `brief` (recommended), or `source` (as written in the source). Default: `"brief"`.
Expand Down
26 changes: 13 additions & 13 deletions src/mkdocstrings_handlers/python/templates/material/_base/docstring.html
View file
Original file line number Diff line number Diff line change
@@ -1,27 +1,27 @@
{% if docstring_sections %}
{{ log.debug("Rendering docstring") }}
{% for section in docstring_sections %}
{% if section.kind.value == "text" %}
{% if config.show_docstring_description and section.kind.value == "text" %}
{{ section.value|convert_markdown(heading_level, html_id) }}
{% elif section.kind.value == "attributes" %}
{% elif config.show_docstring_attributes and section.kind.value == "attributes" %}
{% include "docstring/attributes.html" with context %}
{% elif section.kind.value == "parameters" %}
{% elif config.show_docstring_parameters and section.kind.value == "parameters" %}
{% include "docstring/parameters.html" with context %}
{% elif section.kind.value == "other parameters" %}
{% elif config.show_docstring_other_parameters and section.kind.value == "other parameters" %}
{% include "docstring/other_parameters.html" with context %}
{% elif section.kind.value == "raises" %}
{% elif config.show_docstring_raises and section.kind.value == "raises" %}
{% include "docstring/raises.html" with context %}
{% elif section.kind.value == "warns" %}
{% include "docstring/warns.html" with context %}
{% elif section.kind.value == "yields" %}
{% elif config.show_docstring_warns and section.kind.value == "warns" %}
{% include "docstring/warns.html" with context %}
{% elif config.show_docstring_yields and section.kind.value == "yields" %}
{% include "docstring/yields.html" with context %}
{% elif section.kind.value == "receives" %}
{% include "docstring/receives.html" with context %}
{% elif section.kind.value == "returns" %}
{% elif config.show_docstring_receives and section.kind.value == "receives" %}
{% include "docstring/receives.html" with context %}
{% elif config.show_docstring_returns and section.kind.value == "returns" %}
{% include "docstring/returns.html" with context %}
{% elif section.kind.value == "examples" %}
{% elif config.show_docstring_examples and section.kind.value == "examples" %}
{% include "docstring/examples.html" with context %}
{% elif section.kind.value == "admonition" %}
{% elif config.show_docstring_description and section.kind.value == "admonition" %}
{% include "docstring/admonition.html" with context %}
{% endif %}
{% endfor %}
Expand Down

0 comments on commit a6c55fb

Please sign in to comment.