feat: Add option to merge __init__ methods' docstrings into their c…

…lasses' docstrings
mkdocstrings · Feb 13, 2022 · 1b4d1c0 · 1b4d1c0
1 parent e962b88
commit 1b4d1c0
Show file tree

Hide file tree

Showing 5 changed files with 109 additions and 49 deletions.
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -74,9 +74,15 @@ plugins:
     handlers:
       python:
         import:
+        - https://docs.python.org/3/objects.inv
         - https://mkdocstrings.github.io/objects.inv
+        selection:
+          docstring_style: google
+          docstring_options:
+            ignore_init_summary: yes
         rendering:
           show_submodules: no
+          merge_init_into_class: yes
     watch:
     - src/mkdocstrings_handlers
 

diff --git a/src/mkdocstrings_handlers/python/renderer.py b/src/mkdocstrings_handlers/python/renderer.py
@@ -73,6 +73,7 @@ class PythonRenderer(BaseRenderer):
         "show_signature_annotations": False,
         "separate_signature": False,
         "line_length": 60,
+        "merge_init_into_class": False,
         "show_source": True,
         "show_bases": True,
         "show_submodules": True,
@@ -96,6 +97,7 @@ class PythonRenderer(BaseRenderer):
     **`show_signature_annotations`** | `bool` | Show the type annotations in method and function signatures. | `False`
     **`separate_signature`** | `bool` | Whether to put the whole signature in a code block below the heading. | `False`
     **`line_length`** | `int` | Maximum line length when formatting code. | `60`
+    **`merge_init_into_class`** | `bool` | Whether to merge the `__init__` method into the class' signature and docstring. | `False`
     **`show_source`** | `bool` | Show the source code of this object. | `True`
     **`show_bases`** | `bool` | Show the base classes of a class. | `True`
     **`show_submodules`** | `bool` | When rendering a module, show its submodules recursively. | `True`

diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/children.html b/src/mkdocstrings_handlers/python/templates/material/_base/children.html
@@ -40,8 +40,10 @@
         {% endif %}
         {% with heading_level = heading_level + extra_level %}
           {% for function in obj.functions.values()|order_members(config.members_order) %}
-            {% if not function.is_alias or function.is_explicitely_exported %}
-              {% include "function.html" with context %}
+            {% if not (obj.kind.value == "class" and function.name == "__init__" and config.merge_init_into_class) %}
+              {% if not function.is_alias or function.is_explicitely_exported %}
+                {% include "function.html" with context %}
+              {% endif %}
             {% endif %}
           {% endfor %}
         {% endwith %}
@@ -65,25 +67,29 @@
 
       {% for child in obj.members.values()|order_members(config.members_order) %}
 
-        {% if child.kind.value == "attribute" %}
-          {% with attribute = child %}
-            {% include "attribute.html" with context %}
-          {% endwith %}
+        {% if not (obj.kind.value == "class" and child.name == "__init__" and config.merge_init_into_class) %}
 
-        {% elif child.kind.value == "class" %}
-          {% with class = child %}
-            {% include "class.html" with context %}
-          {% endwith %}
+          {% if child.kind.value == "attribute" %}
+            {% with attribute = child %}
+              {% include "attribute.html" with context %}
+            {% endwith %}
 
-        {% elif child.kind.value == "function" %}
-          {% with function = child %}
-            {% include "function.html" with context %}
-          {% endwith %}
+          {% elif child.kind.value == "class" %}
+            {% with class = child %}
+              {% include "class.html" with context %}
+            {% endwith %}
 
-        {% elif child.kind.value == "module" and config.show_submodules %}
-          {% with module = child %}
-            {% include "module.html" with context %}
-          {% endwith %}
+          {% elif child.kind.value == "function" %}
+            {% with function = child %}
+              {% include "function.html" with context %}
+            {% endwith %}
+
+          {% elif child.kind.value == "module" and config.show_submodules %}
+            {% with module = child %}
+              {% include "module.html" with context %}
+            {% endwith %}
+
+          {% endif %}
 
         {% endif %}
 

diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/class.html b/src/mkdocstrings_handlers/python/templates/material/_base/class.html
@@ -22,21 +22,40 @@
           class="doc doc-heading",
           toc_label=class.name) %}
 
-        <code>
-          {% if show_full_path %}{{ class.path }}{% else %}{{ class.name }}{% endif %}
-          {% if config.show_bases and class.bases %}
-            ({% for expression in class.bases -%}
-              {% include "expression.html" with context %}{% if not loop.last %}, {% endif %}
-             {% endfor %})
-          {% endif %}
-        </code>
+        {% if config.separate_signature %}
+          <code>{% if show_full_path %}{{ class.path }}{% else %}{{ class.name }}{% endif %}</code>
+        {% elif config.merge_init_into_class and "__init__" in class.members -%}
+          {%- with function = class.members["__init__"] -%}
+            {%- filter highlight(language="python", inline=True) -%}
+              {% if show_full_path %}{{ class.path }}{% else %}{{ class.name }}{% endif %}
+              {% with no_self = True %}
+                {%- include "signature.html" with context -%}
+              {% endwith %}
+            {%- endfilter -%}
+          {%- endwith -%}
+        {% else %}
+          <code>{% if show_full_path %}{{ class.path }}{% else %}{{ class.name }}{% endif %}</code>
+        {% endif %}
 
         {% with labels = class.labels %}
           {% include "labels.html" with context %}
         {% endwith %}
 
       {% endfilter %}
 
+      {% if config.separate_signature and config.merge_init_into_class %}
+        {% if "__init__" in class.members %}
+          {% with function = class.members["__init__"], no_self = True %}
+            {% filter highlight(language="python", inline=False) %}
+              {% filter format_signature(config.line_length) %}        
+                {% if show_full_path %}{{ class.path }}{% else %}{{ class.name }}{% endif %}
+                {% include "signature.html" with context %}
+              {% endfilter %}
+            {% endfilter %}
+          {% endwith %}
+        {% endif %}
+      {% endif %}
+
     {% else %}
       {% if config.show_root_toc_entry %}
         {% filter heading(heading_level,
@@ -50,15 +69,40 @@
     {% endif %}
 
     <div class="doc doc-contents {% if root %}first{% endif %}">
+      {% if config.show_bases and class.bases %}
+        <p class="doc doc-class-bases">
+          Bases: {% for expression in class.bases -%}
+            <code>{% include "expression.html" with context %}</code>{% if not loop.last %}, {% endif %}
+          {% endfor -%}
+        </p>
+      {% endif %}
+
       {% with docstring_sections = class.docstring.parsed %}
         {% include "docstring.html" with context %}
       {% endwith %}
 
-      {% if config.show_source and class.source %}
-        <details class="quote">
-          <summary>Source code in <code>{{ class.relative_filepath }}</code></summary>
-          {{ class.source|highlight(language="python", linestart=class.lineno, linenums=True) }}
-        </details>
+      {% if config.merge_init_into_class %}
+        {% if "__init__" in class.members and class.members["__init__"].has_docstring %}
+          {% with docstring_sections = class.members["__init__"].docstring.parsed %}
+            {% include "docstring.html" with context %}
+          {% endwith %}
+        {% endif %}
+      {% endif %}
+
+      {% if config.show_source %}
+        {% if config.merge_init_into_class %}
+          {% if "__init__" in class.members %}
+            <details class="quote">
+              <summary>Source code in <code>{{ class.relative_filepath }}</code></summary>
+              {{ class.members["__init__"].source|highlight(language="python", linestart=class.lineno, linenums=True) }}
+            </details>
+          {% endif %}
+        {% elif class.source %}
+          <details class="quote">
+            <summary>Source code in <code>{{ class.relative_filepath }}</code></summary>
+            {{ class.source|highlight(language="python", linestart=class.lineno, linenums=True) }}
+          </details>
+        {% endif %}
       {% endif %}
 
       {% with obj = class %}

diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/signature.html b/src/mkdocstrings_handlers/python/templates/material/_base/signature.html
@@ -10,30 +10,32 @@
 
     (
       {%- for parameter in function.parameters -%}
+        {%- if parameter.name != "self" or not no_self -%}
 
-        {%- if parameter.kind.value == "positional-only" -%}
-          {%- if ns.render_pos_only_separator -%}
-            {%- set ns.render_pos_only_separator = False %}/, {% endif -%}
-        {%- elif parameter.kind.value == "keyword-only" -%}
-          {%- if ns.render_kw_only_separator -%}
-            {%- set ns.render_kw_only_separator = False %}*, {% endif -%}
-        {%- endif -%}
+          {%- if parameter.kind.value == "positional-only" -%}
+            {%- if ns.render_pos_only_separator -%}
+              {%- set ns.render_pos_only_separator = False %}/, {% endif -%}
+          {%- elif parameter.kind.value == "keyword-only" -%}
+            {%- if ns.render_kw_only_separator -%}
+              {%- set ns.render_kw_only_separator = False %}*, {% endif -%}
+          {%- endif -%}
 
-        {%- if config.show_signature_annotations and parameter.annotation is not none -%}
-          {%- set annotation = ": " + parameter.annotation|safe -%}
-        {%- endif -%}
+          {%- if config.show_signature_annotations and parameter.annotation is not none -%}
+            {%- set annotation = ": " + parameter.annotation|safe -%}
+          {%- endif -%}
 
-        {%- if parameter.default is not none and parameter.kind.value != "variadic positional" and parameter.kind.value != "variadic keyword" -%}
-          {%- set default = ns.equal + parameter.default|safe -%}
-        {%- endif -%}
+          {%- if parameter.default is not none and parameter.kind.value != "variadic positional" and parameter.kind.value != "variadic keyword" -%}
+            {%- set default = ns.equal + parameter.default|safe -%}
+          {%- endif -%}
 
-        {%- if parameter.kind.value == "variadic positional" -%}
-          {%- set ns.render_kw_only_separator = False -%}
-        {%- endif -%}
+          {%- if parameter.kind.value == "variadic positional" -%}
+            {%- set ns.render_kw_only_separator = False -%}
+          {%- endif -%}
 
-        {{ parameter.name }}{{ annotation }}{{ default }}
-        {%- if not loop.last %}, {% endif -%}
+          {{ parameter.name }}{{ annotation }}{{ default }}
+          {%- if not loop.last %}, {% endif -%}
 
+        {%- endif -%}
       {%- endfor -%}
     )
     {%- if config.show_signature_annotations and "return_annotation" in signature %} -> {{ signature.return_annotation }}{%- endif -%}