Merge pull request #28 from ray-project/typography

typography changes to make headings stand out more

Author: maxpumperla

docs/css/extra.css

@@ -57,4 +57,15 @@ label[for="__drawer"] {
 /* reduce the top margin of the main container */
 .md-main__inner {
     margin-top: 0;
+}
+
+/* make the method names in API references stand out more */
+.md-typeset h3 {
+    font-weight: bold;
+    font-size: 1.4em;
+}
+
+/* swap the top/bottom margin of h1 */
+.md-typeset h1 {
+    margin: 1.25em 0 0;
 }

mkdocs.yml

@@ -68,6 +68,7 @@ plugins:
             filters:
               - "!^_"  # exlude all members starting with _
               - "^__init__$"  # but always include __init__ modules and methods
+      custom_templates: templates
 
 
 markdown_extensions:

templates/python/material/method.html

@@ -0,0 +1,66 @@
+{{ log.debug() }}
+{% if config.show_if_no_docstring or method.has_contents %}
+
+  <div class="doc doc-object doc-method">
+  {% with html_id = method.path %}
+
+    {% if not root or config.show_root_heading %}
+
+      {% if root %}
+        {% set show_full_path = config.show_root_full_path %}
+        {% set root_members = True %}
+      {% elif root_members %}
+        {% set show_full_path = config.show_root_members_full_path or config.show_object_full_path %}
+        {% set root_members = False %}
+      {% else %}
+        {% set show_full_path = config.show_object_full_path %}
+      {% endif %}
+
+      {% filter heading(heading_level,
+          role="method",
+          id=html_id,
+          class="doc doc-heading",
+          toc_label=method.name ~ "()") %}
+
+        {{ method.name }}
+
+        {% with properties = method.properties %}
+          {% include "properties.html" with context %}
+        {% endwith %}
+
+      {% endfilter %}
+
+    {% else %}
+      {% if config.show_root_toc_entry %}
+        {% filter heading(heading_level,
+            role="method",
+            id=html_id,
+            toc_label=method.path,
+            hidden=True) %}
+        {% endfilter %}
+      {% endif %}
+      {% set heading_level = heading_level - 1 %}
+    {% endif %}
+
+    <div class="doc doc-contents {% if root %}first{% endif %}">
+      {% filter highlight(language="python", inline=True) %}
+          {% if show_full_path %}{{ method.path }}{% else %}{{ method.name }}{% endif %}
+          {% with signature = method.signature %}{% include "signature.html" with context %}{% endwith %}
+      {% endfilter %}
+
+      {% with docstring_sections = method.docstring_sections %}
+        {% include "docstring.html" with context %}
+      {% endwith %}
+
+      {% if config.show_source and method.source %}
+        <details class="quote">
+          <summary>Source code in <code>{{ method.relative_file_path }}</code></summary>
+          {{ method.source.code|highlight(language="python", linestart=method.source.line_start, linenums=False) }}
+        </details>
+      {% endif %}
+    </div>
+
+  {% endwith %}
+  </div>
+
+{% endif %}