refactor: Make source admonitions more subtle

Issue-mkdocstrings#525: mkdocstrings/mkdocstrings#525

Author: pawamoy

mkdocs.yml

@@ -174,7 +174,7 @@ plugins:
           show_root_heading: true
           show_root_full_path: false
           show_signature_annotations: true
-          show_source: false
+          show_source: true
           show_symbol_type_heading: true
           show_symbol_type_toc: true
           signature_crossrefs: true

src/mkdocstrings_handlers/python/templates/material/_base/class.html.jinja

@@ -102,6 +102,43 @@ Context:
     {% endif %}
 
     <div class="doc doc-contents {% if root %}first{% endif %}">
+
+      {% block source scoped %}
+        {#- Source block.
+        
+        This block renders the source code for the class.
+        -#}
+        {% if config.show_source %}
+          {% if config.merge_init_into_class %}
+            {% if "__init__" in class.all_members and class.all_members["__init__"].source %}
+              {% with init = class.all_members["__init__"] %}
+                <details class="source">
+                  <summary>Source code in <code>
+                    {%- if init.relative_filepath.is_absolute() -%}
+                      {{ init.relative_package_filepath }}
+                    {%- else -%}
+                      {{ init.relative_filepath }}
+                    {%- endif -%}
+                  </code></summary>
+                  {{ init.source|highlight(language="python", linestart=init.lineno or 0, linenums=True) }}
+                </details>
+              {% endwith %}
+            {% endif %}
+          {% elif class.source %}
+            <details class="source">
+              <summary>Source code in <code>
+                {%- if class.relative_filepath.is_absolute() -%}
+                  {{ class.relative_package_filepath }}
+                {%- else -%}
+                  {{ class.relative_filepath }}
+                {%- endif -%}
+              </code></summary>
+              {{ class.source|highlight(language="python", linestart=class.lineno or 0, linenums=True) }}
+            </details>
+          {% endif %}
+        {% endif %}
+      {% endblock source %}
+
       {% block contents scoped %}
         {#- Contents block.
         
@@ -150,42 +187,6 @@ Context:
           {% include "summary"|get_template with context %}
         {% endblock summary %}
 
-        {% block source scoped %}
-          {#- Source block.
-          
-          This block renders the source code for the class.
-          -#}
-          {% if config.show_source %}
-            {% if config.merge_init_into_class %}
-              {% if "__init__" in class.all_members and class.all_members["__init__"].source %}
-                {% with init = class.all_members["__init__"] %}
-                  <details class="quote">
-                    <summary>Source code in <code>
-                      {%- if init.relative_filepath.is_absolute() -%}
-                        {{ init.relative_package_filepath }}
-                      {%- else -%}
-                        {{ init.relative_filepath }}
-                      {%- endif -%}
-                    </code></summary>
-                    {{ init.source|highlight(language="python", linestart=init.lineno or 0, linenums=True) }}
-                  </details>
-                {% endwith %}
-              {% endif %}
-            {% elif class.source %}
-              <details class="quote">
-                <summary>Source code in <code>
-                  {%- if class.relative_filepath.is_absolute() -%}
-                    {{ class.relative_package_filepath }}
-                  {%- else -%}
-                    {{ class.relative_filepath }}
-                  {%- endif -%}
-                </code></summary>
-                {{ class.source|highlight(language="python", linestart=class.lineno or 0, linenums=True) }}
-              </details>
-            {% endif %}
-          {% endif %}
-        {% endblock source %}
-
         {% block children scoped %}
           {#- Children block.
           

src/mkdocstrings_handlers/python/templates/material/_base/function.html.jinja

@@ -80,6 +80,11 @@ Context:
         This block renders the signature for the function,
         as well as its overloaded signatures if any.
         -#}
+        {% with source = function.lines[function.docstring.endlineno-function.lineno+1:] %}
+        {% if source %}
+        <details class="source">
+        <summary>
+        {% endif %}
         {% if function.overloads %}
           <div class="doc-overloads">
             {% for overload in function.overloads %}
@@ -94,6 +99,12 @@ Context:
             {{ function.name }}
           {% endfilter %}
         {% endif %}
+        {% if source %}
+        </summary>
+        {{ source|join("\n")|highlight(language="python", linestart=function.docstring.endlineno+1 or 0, linenums=True) }}
+        </details>
+        {% endif %}
+        {% endwith %}
       {% endblock signature %}
 
     {% else %}
@@ -119,6 +130,7 @@ Context:
         It contains other blocks that users can override.
         Overriding the contents block allows to rearrange the order of the blocks.
         -#}
+        <a href="/sources/{{ function.relative_package_filepath.with_suffix('') }}/" target="_blank">View source</a>
         {% block docstring scoped %}
           {#- Docstring block.
           
@@ -128,25 +140,6 @@ Context:
             {% include "docstring"|get_template with context %}
           {% endwith %}
         {% endblock docstring %}
-
-        {% block source scoped %}
-          {#- Source block.
-          
-          This block renders the source code for the function.
-          -#}
-          {% if config.show_source and function.source %}
-            <details class="quote">
-              <summary>{{ lang.t("Source code in") }} <code>
-                {%- if function.relative_filepath.is_absolute() -%}
-                  {{ function.relative_package_filepath }}
-                {%- else -%}
-                  {{ function.relative_filepath }}
-                {%- endif -%}
-              </code></summary>
-              {{ function.source|highlight(language="python", linestart=function.lineno or 0, linenums=True) }}
-            </details>
-          {% endif %}
-        {% endblock source %}
       {% endblock contents %}
     </div>
 

src/mkdocstrings_handlers/python/templates/material/style.css

@@ -140,3 +140,48 @@ code.doc-symbol-module::after {
   color: inherit;
   border-bottom: 1px dotted currentcolor;
 }
+
+:root {
+  --md-admonition-icon--source: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="m14.6 16.6 4.6-4.6-4.6-4.6L16 6l6 6-6 6zm-5.2 0L4.8 12l4.6-4.6L8 6l-6 6 6 6z"/></svg>')
+  /* --md-admonition-icon--source: "" */
+}
+.md-typeset .admonition.source,
+.md-typeset details.source {
+  border-color: var(--md-code-bg-color);
+}
+.md-typeset .source > .admonition-title,
+.md-typeset .source > summary {
+  background-color: var(--md-code-bg-color);
+}
+.md-typeset .source > .admonition-title::before,
+.md-typeset .source > summary::before {
+  /* background-color: rgb(128, 128, 128); */
+  background-color: var(--md-code-bg-color);
+  /* -webkit-mask-image: var(--md-admonition-icon--source);
+          mask-image: var(--md-admonition-icon--source); */
+  -webkit-mask-image: unset;
+          mask-image: unset;
+}
+
+.doc details.source {
+  background-color: var(--md-code-bg-color);
+  border: 0;
+  border-radius: 0;
+  margin: 0;
+  padding: 0;
+  transition: none;
+}
+
+.doc details.source summary {
+  background-color: inherit;
+  border: 0;
+  border-radius: 0;
+  padding-top: 0;
+  padding-bottom: 0;
+}
+
+
+.doc details.source summary code {
+  box-shadow: none;
+  padding: 0;
+}