Improve method source toggling (#1176)

* Move method source block to the top

Currently, if a method description is long (e.g. `Array.new`), users need
to click the method toggle button next to the method title, and then scroll
down to the source code expanded below the description.

This commit changes the behavior so that the source code is expanded
immediately below the method title.

* Update method toggle's interface

1. Display the method toggle button by default instead of displaying on hover
2. Only toggle the source code when clicking the method toggle button, not
   when clicking the entire method title section. This will allow us to display
   an anchor link next to the method title
3. Simplify the toggle source button's appearance

* Use details tag for method toggling

* Rename method-click-advice to method-source-toggle

* Improve method controls' display on mobile

By moving the method controls out of the method header, we can display
them to the right of the method name on desktop, and below the method name
on mobile.

* Add "Example" label to example code blocks

The label should help users distinguish example code blocks from other
code blocks, such as method source code.

It's only applied to Ruby code examples.

* Revert "Add "Example" label to example code blocks"

This reverts commit 69fc9ce.

* Give source code blocks a different background color

* Change targeted method's highlighting color to work better with the new method source

Author: st0012

lib/rdoc/generator/template/darkfish/class.rhtml

@@ -101,35 +101,42 @@
       <div id="<%= method.aref %>" class="method-detail <%= method.is_alias_for ? "method-alias" : '' %>">
         <div class="method-header">
           <%- if (call_seq = method.call_seq) then -%>
-          <%-   call_seq.strip.split("\n").each_with_index do |call_seq, i| -%>
-          <div class="method-heading">
-            <span class="method-callseq">
-              <%= h(call_seq.strip.
-                    gsub( /^\w+\./m, '')).
-                    gsub(/(.*)[-=]&gt;/, '\1&rarr;') %>
-            </span>
-            <%- if i == 0 and method.token_stream then -%>
-            <span class="method-click-advice">click to toggle source</span>
+            <%- call_seq.strip.split("\n").each_with_index do |call_seq, i| -%>
+              <div class="method-heading">
+                <span class="method-callseq">
+                  <%= h(call_seq.strip.
+                        gsub( /^\w+\./m, '')).
+                        gsub(/(.*)[-=]&gt;/, '\1&rarr;') %>
+                </span>
+              </div>
             <%- end -%>
-          </div>
-          <%-   end -%>
           <%- elsif method.has_call_seq? then -%>
-          <div class="method-heading">
-            <span class="method-name"><%= h method.name %></span>
-          </div>
+            <div class="method-heading">
+              <span class="method-name"><%= h method.name %></span>
+            </div>
           <%- else -%>
-          <div class="method-heading">
-            <span class="method-name"><%= h method.name %></span><span
-              class="method-args"><%= h method.param_seq %></span>
-            <%- if method.token_stream then -%>
-            <span class="method-click-advice">click to toggle source</span>
-            <%- end -%>
-          </div>
+            <div class="method-heading">
+              <span class="method-name"><%= h method.name %></span>
+              <span class="method-args"><%= h method.param_seq %></span>
+            </div>
           <%- end -%>
         </div>
 
+        <%- if method.token_stream -%>
+          <div class="method-controls">
+            <details class="method-source-toggle">
+              <summary>Source</summary>
+            </details>
+          </div>
+        <%- end -%>
+
         <%- unless method.skip_description? then -%>
         <div class="method-description">
+          <%- if method.token_stream then -%>
+          <div class="method-source-code" id="<%= method.html_name %>-source">
+            <pre><%= method.markup_code %></pre>
+          </div>
+          <%- end -%>
           <%- if method.comment then -%>
           <%= method.description.strip %>
           <%- else -%>
@@ -144,12 +151,6 @@
               %>
             </div>
           <%- end -%>
-
-          <%- if method.token_stream then -%>
-          <div class="method-source-code" id="<%= method.html_name %>-source">
-            <pre><%= method.markup_code %></pre>
-          </div>
-          <%- end -%>
         </div>
         <%- end -%>
 

lib/rdoc/generator/template/darkfish/css/rdoc.css

@@ -22,6 +22,7 @@
   --link-hover-color: #25a28a;  /* A slightly brighter teal-green */
   --border-color: #e0e0e0;
   --sidebar-text-color: #2c3e50;  /* Dark blue-gray for contrast */
+  --source-code-background-color: #e8f0eb;
 
   /* Font family variables */
   --font-primary: 'Lato', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen-Sans, Ubuntu, Cantarell, 'Helvetica Neue', sans-serif;
@@ -595,6 +596,10 @@ main .method-source-code {
   transition-timing-function: ease-in-out;
 }
 
+main .method-source-code pre {
+  background: var(--source-code-background-color);
+}
+
 main .method-source-code.active-menu {
   visibility: visible;
   max-height: 100vh;
@@ -607,12 +612,15 @@ main .method-description .method-calls-super {
 
 main .method-detail {
   margin-bottom: 2.5em;
-  cursor: pointer;
 }
 
 main .method-detail:target {
   margin-left: -10px;
-  border-left: 10px solid #f1edba;
+  border-left: 10px solid var(--source-code-background-color);
+}
+
+main .method-header {
+  display: inline-block;
 }
 
 main .method-heading {
@@ -622,23 +630,12 @@ main .method-heading {
   font-weight: bold;
   color: var(--text-color);
 }
-main .method-heading :link,
-main .method-heading :visited {
-  color: inherit;
-}
-main .method-click-advice {
-  position: absolute;
-  top: 2px;
-  right: 5px;
-  font-size: 12px;
-  color: #9b9877;
-  visibility: hidden;
-  padding-right: 20px;
+
+main .method-controls {
   line-height: 20px;
-  background: url(../images/zoom.png) no-repeat right top;
-}
-main .method-header:hover .method-click-advice {
-  visibility: visible;
+  float: right;
+  color: var(--secondary-color);
+  cursor: pointer;
 }
 
 main .method-alias .method-heading {
@@ -743,6 +740,11 @@ main .attribute-access-type {
     overflow-x: auto;
     white-space: nowrap;
   }
+
+  main .method-controls {
+    margin-top: 10px;
+    float: none;
+  }
 }
 /* @end */
 

lib/rdoc/generator/template/darkfish/js/darkfish.js

@@ -34,7 +34,7 @@ function showSource( e ) {
 };
 
 function hookSourceViews() {
-  document.querySelectorAll('.method-heading').forEach(function (codeObject) {
+  document.querySelectorAll('.method-source-toggle').forEach(function (codeObject) {
     codeObject.addEventListener('click', showSource);
   });
 };