feat: add new show options for docstrings

mkdocstrings · pawamoy · Feb 3, 2023 · Jan 29, 2023 · Feb 3, 2023 · Feb 3, 2023
commit b587eb5fd0d85763588d449f26ab734e545f58aa
diff --git a/docs/schema.json b/docs/schema.json
@@ -140,8 +140,74 @@
               "type": "boolean",
               "default": false
             },
+            "show_docstring_section_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_section_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_section_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_section_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_section_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_section_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_docstring_section_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_section_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_section_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_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_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
+            },
+            "show_function_title": {
+              "title": "Whether to display the title of the function/class method object.",
               "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options",
               "type": "boolean",
               "default": true

diff --git a/src/mkdocstrings_handlers/python/handler.py b/src/mkdocstrings_handlers/python/handler.py
@@ -79,6 +79,17 @@ class PythonHandler(BaseHandler):
         "separate_signature": False,
         "line_length": 60,
         "merge_init_into_class": False,
+        "show_docstring_section_attributes": True,
+        "show_docstring_section_parameters": True,
+        "show_docstring_section_other_parameters": True,
+        "show_docstring_section_raises": True,
+        "show_docstring_section_warns": True,
+        "show_docstring_section_yields": True,
+        "show_docstring_section_receives": True,
+        "show_docstring_section_returns": True,
+        "show_docstring_section_examples": True,
+        "show_docstring_description": True,
+        "show_function_title": True,
         "show_source": True,
         "show_bases": True,
         "show_submodules": False,
@@ -119,6 +130,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_section_attributes (bool): Whether to display the "Attributes" section in the object's docstring. Default: `True`.
+        show_docstring_section_parameters (bool): Whether to display the "Parameters" section in the object's docstring. Default: `True`.
+        show_docstring_section_other_parameters (bool): Whether to display the "Other Parameters" section in the object's docstring. Default: `True`.
+        show_docstring_section_raises (bool): Whether to display the "Raises" section in the object's docstring. Default: `True`.
+        show_docstring_section_warns (bool): Whether to display the "Warns" section in the object's docstring. Default: `True`.
+        show_docstring_section_yields (bool): Whether to display the "Yields" section in the object's docstring. Default: `True`.
+        show_docstring_section_receives (bool): Whether to display the "Receives" section in the object's docstring. Default: `True`.
+        show_docstring_section_returns (bool): Whether to display the "Returns" section in the object's docstring. Default: `True`.
+        show_docstring_section_examples (bool): Whether to display the "Examples" 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`.
 
     Attributes: Signatures/annotations options:
         annotations_path (str): The verbosity for annotations path: `brief` (recommended), or `source` (as written in the source). Default: `"brief"`.
@@ -128,6 +149,7 @@ class PythonHandler(BaseHandler):
             If Black is installed, the signature is also formatted using it. Default: `False`.
 
     Attributes: Additional options:
+        show_function_title (bool): Whether to display the title of the function/class method object. Default: `True`.
         show_bases (bool): Show the base classes of a class. Default: `True`.
         show_source (bool): Show the source code of this object. Default: `True`.
     """  # noqa: E501

diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring.html b/src/mkdocstrings_handlers/python/templates/material/_base/docstring.html
@@ -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_section_attributes and section.kind.value == "attributes" %}
       {% include "docstring/attributes.html" with context %}
-    {% elif section.kind.value == "parameters" %}
+    {% elif config.show_docstring_section_parameters and section.kind.value == "parameters" %}
       {% include "docstring/parameters.html" with context %}
-    {% elif section.kind.value == "other parameters" %}
+    {% elif config.show_docstring_section_other_parameters and section.kind.value == "other parameters" %}
       {% include "docstring/other_parameters.html" with context %}
-    {% elif section.kind.value == "raises" %}
+    {% elif config.show_docstring_section_raises and section.kind.value == "raises" %}
       {% include "docstring/raises.html" with context %}
-      {% elif section.kind.value == "warns" %}
+    {% elif config.show_docstring_section_warns and section.kind.value == "warns" %}
         {% include "docstring/warns.html" with context %}
-    {% elif section.kind.value == "yields" %}
+    {% elif config.show_docstring_section_yields and section.kind.value == "yields" %}
       {% include "docstring/yields.html" with context %}
-      {% elif section.kind.value == "receives" %}
+    {% elif config.show_docstring_section_receives and section.kind.value == "receives" %}
         {% include "docstring/receives.html" with context %}
-    {% elif section.kind.value == "returns" %}
+    {% elif config.show_docstring_section_returns and section.kind.value == "returns" %}
       {% include "docstring/returns.html" with context %}
-    {% elif section.kind.value == "examples" %}
+    {% elif config.show_docstring_section_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 %}

diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/function.html b/src/mkdocstrings_handlers/python/templates/material/_base/function.html
@@ -13,49 +13,51 @@
     {% set show_full_path = config.show_object_full_path %}
   {% endif %}
 
-  {% if not root or config.show_root_heading %}
+  {%- if config.show_function_title -%}
+    {% if not root or config.show_root_heading %}
 
-    {% filter heading(heading_level,
-        role="function",
-        id=html_id,
-        class="doc doc-heading",
-        toc_label=function.name ~ "()") %}
+      {% filter heading(heading_level,
+          role="function",
+          id=html_id,
+          class="doc doc-heading",
+          toc_label=function.name ~ "()") %}
 
-      {% if config.separate_signature %}
-        <span class="doc doc-object-name doc-function-name">{% if show_full_path %}{{ function.path }}{% else %}{{ function.name }}{% endif %}</span>
-      {% else %}
-        {% filter highlight(language="python", inline=True) %}
-          {% if show_full_path %}{{ function.path }}{% else %}{{ function.name }}{% endif %}
-          {% include "signature.html" with context %}
-        {% endfilter %}
-      {% endif %}
+        {% if config.separate_signature %}
+          <span class="doc doc-object-name doc-function-name">{% if show_full_path %}{{ function.path }}{% else %}{{ function.name }}{% endif %}</span>
+        {% else %}
+          {% filter highlight(language="python", inline=True) %}
+            {% if show_full_path %}{{ function.path }}{% else %}{{ function.name }}{% endif %}
+            {% include "signature.html" with context %}
+          {% endfilter %}
+        {% endif %}
 
-      {% with labels = function.labels %}
-        {% include "labels.html" with context %}
-      {% endwith %}
+        {% with labels = function.labels %}
+          {% include "labels.html" with context %}
+        {% endwith %}
 
-    {% endfilter %}
+      {% endfilter %}
 
-    {% if config.separate_signature %}
-      {% filter highlight(language="python", inline=False) %}
-        {% filter format_signature(config.line_length) %}
-          {% if show_full_path %}{{ function.path }}{% else %}{{ function.name }}{% endif %}
-          {% include "signature.html" with context %}
+      {% if config.separate_signature %}
+        {% filter highlight(language="python", inline=False) %}
+          {% filter format_signature(config.line_length) %}
+            {% if show_full_path %}{{ function.path }}{% else %}{{ function.name }}{% endif %}
+            {% include "signature.html" with context %}
+          {% endfilter %}
         {% endfilter %}
-      {% endfilter %}
-    {% endif %}
+      {% endif %}
 
-  {% else %}
-    {% if config.show_root_toc_entry %}
-      {% filter heading(heading_level,
-          role="function",
-          id=html_id,
-          toc_label=function.path if config.show_root_full_path else function.name,
-          hidden=True) %}
-      {% endfilter %}
+    {% else %}
+      {% if config.show_root_toc_entry %}
+        {% filter heading(heading_level,
+            role="function",
+            id=html_id,
+            toc_label=function.path if config.show_root_full_path else function.name,
+            hidden=True) %}
+        {% endfilter %}
+      {% endif %}
+      {% set heading_level = heading_level - 1 %}
     {% endif %}
-    {% set heading_level = heading_level - 1 %}
-  {% endif %}
+  {%- endif -%}
 
   <div class="doc doc-contents {% if root %}first{% endif %}">
     {% with docstring_sections = function.docstring.parsed %}