From 6ea31ebee6fdd432e97b8f29501e008ea5577000 Mon Sep 17 00:00:00 2001
From: Stan Lo <stan.lo@shopify.com>
Date: Sun, 8 Sep 2024 13:47:13 +0100
Subject: [PATCH 1/9] 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.
---
 lib/rdoc/generator/template/darkfish/class.rhtml | 11 +++++------
 1 file changed, 5 insertions(+), 6 deletions(-)

diff --git a/lib/rdoc/generator/template/darkfish/class.rhtml b/lib/rdoc/generator/template/darkfish/class.rhtml
index 6c64ba6c98..3d801ce3db 100644
--- a/lib/rdoc/generator/template/darkfish/class.rhtml
+++ b/lib/rdoc/generator/template/darkfish/class.rhtml
@@ -130,6 +130,11 @@
 
         <%- 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 +149,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 -%>
 

From 86039f954bfd9a4b36c9f08a0c60a9c136e4d143 Mon Sep 17 00:00:00 2001
From: Stan Lo <stan.lo@shopify.com>
Date: Sun, 8 Sep 2024 13:51:20 +0100
Subject: [PATCH 2/9] 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
---
 lib/rdoc/generator/template/darkfish/class.rhtml    |  4 ++--
 lib/rdoc/generator/template/darkfish/css/rdoc.css   | 11 +++--------
 lib/rdoc/generator/template/darkfish/js/darkfish.js |  2 +-
 3 files changed, 6 insertions(+), 11 deletions(-)

diff --git a/lib/rdoc/generator/template/darkfish/class.rhtml b/lib/rdoc/generator/template/darkfish/class.rhtml
index 3d801ce3db..d95c7d7182 100644
--- a/lib/rdoc/generator/template/darkfish/class.rhtml
+++ b/lib/rdoc/generator/template/darkfish/class.rhtml
@@ -109,7 +109,7 @@
                     gsub(/(.*)[-=]&gt;/, '\1&rarr;') %>
             </span>
             <%- if i == 0 and method.token_stream then -%>
-            <span class="method-click-advice">click to toggle source</span>
+            <span class="method-click-advice">Toggle source</span>
             <%- end -%>
           </div>
           <%-   end -%>
@@ -122,7 +122,7 @@
             <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>
+            <span class="method-click-advice">Toggle source</span>
             <%- end -%>
           </div>
           <%- end -%>
diff --git a/lib/rdoc/generator/template/darkfish/css/rdoc.css b/lib/rdoc/generator/template/darkfish/css/rdoc.css
index 7a42e62522..4632603546 100644
--- a/lib/rdoc/generator/template/darkfish/css/rdoc.css
+++ b/lib/rdoc/generator/template/darkfish/css/rdoc.css
@@ -608,7 +608,6 @@ main .method-description .method-calls-super {
 
 main .method-detail {
   margin-bottom: 2.5em;
-  cursor: pointer;
 }
 
 main .method-detail:target {
@@ -630,16 +629,12 @@ main .method-heading :visited {
 main .method-click-advice {
   position: absolute;
   top: 2px;
-  right: 5px;
+  right: 0px;
   font-size: 12px;
-  color: #9b9877;
-  visibility: hidden;
   padding-right: 20px;
   line-height: 20px;
-  background: url(../images/zoom.png) no-repeat right top;
-}
-main .method-header:hover .method-click-advice {
-  visibility: visible;
+  color: var(--secondary-color);
+  cursor: pointer;
 }
 
 main .method-alias .method-heading {
diff --git a/lib/rdoc/generator/template/darkfish/js/darkfish.js b/lib/rdoc/generator/template/darkfish/js/darkfish.js
index bea0a5f1cb..ad67b61656 100644
--- a/lib/rdoc/generator/template/darkfish/js/darkfish.js
+++ b/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-click-advice').forEach(function (codeObject) {
     codeObject.addEventListener('click', showSource);
   });
 };

From daf6b060bece49cba59154c4ed8e84ccff25e0e0 Mon Sep 17 00:00:00 2001
From: Stan Lo <stan.lo@shopify.com>
Date: Sun, 8 Sep 2024 22:22:28 +0100
Subject: [PATCH 3/9] Use details tag for method toggling

---
 lib/rdoc/generator/template/darkfish/class.rhtml | 16 ++++++++++++----
 .../generator/template/darkfish/css/rdoc.css     | 10 +++++++++-
 2 files changed, 21 insertions(+), 5 deletions(-)

diff --git a/lib/rdoc/generator/template/darkfish/class.rhtml b/lib/rdoc/generator/template/darkfish/class.rhtml
index d95c7d7182..171dba7472 100644
--- a/lib/rdoc/generator/template/darkfish/class.rhtml
+++ b/lib/rdoc/generator/template/darkfish/class.rhtml
@@ -109,7 +109,11 @@
                     gsub(/(.*)[-=]&gt;/, '\1&rarr;') %>
             </span>
             <%- if i == 0 and method.token_stream then -%>
-            <span class="method-click-advice">Toggle source</span>
+            <div class="method-controls">
+              <details class="method-click-advice">
+                <summary>Source</summary>
+              </details>
+            </div>
             <%- end -%>
           </div>
           <%-   end -%>
@@ -119,10 +123,14 @@
           </div>
           <%- else -%>
           <div class="method-heading">
-            <span class="method-name"><%= h method.name %></span><span
-              class="method-args"><%= h method.param_seq %></span>
+            <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">Toggle source</span>
+            <div class="method-controls">
+              <details class="method-click-advice">
+                <summary>Source</summary>
+              </details>
+            </div>
             <%- end -%>
           </div>
           <%- end -%>
diff --git a/lib/rdoc/generator/template/darkfish/css/rdoc.css b/lib/rdoc/generator/template/darkfish/css/rdoc.css
index 4632603546..21d2e961f5 100644
--- a/lib/rdoc/generator/template/darkfish/css/rdoc.css
+++ b/lib/rdoc/generator/template/darkfish/css/rdoc.css
@@ -630,7 +630,6 @@ main .method-click-advice {
   position: absolute;
   top: 2px;
   right: 0px;
-  font-size: 12px;
   padding-right: 20px;
   line-height: 20px;
   color: var(--secondary-color);
@@ -739,6 +738,15 @@ main .attribute-access-type {
     overflow-x: auto;
     white-space: nowrap;
   }
+
+  .method-controls {
+    position: static;
+  }
+
+  main .method-click-advice {
+    position: static;
+    display: inline-block;
+  }
 }
 /* @end */
 

From 1dd027827ddfa38e894a24873bc8fa5637dae4a7 Mon Sep 17 00:00:00 2001
From: Stan Lo <stan.lo@shopify.com>
Date: Sun, 8 Sep 2024 23:22:19 +0100
Subject: [PATCH 4/9] Rename method-click-advice to method-source-toggle

---
 lib/rdoc/generator/template/darkfish/class.rhtml    | 4 ++--
 lib/rdoc/generator/template/darkfish/css/rdoc.css   | 4 ++--
 lib/rdoc/generator/template/darkfish/js/darkfish.js | 2 +-
 3 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/lib/rdoc/generator/template/darkfish/class.rhtml b/lib/rdoc/generator/template/darkfish/class.rhtml
index 171dba7472..683b47cf51 100644
--- a/lib/rdoc/generator/template/darkfish/class.rhtml
+++ b/lib/rdoc/generator/template/darkfish/class.rhtml
@@ -110,7 +110,7 @@
             </span>
             <%- if i == 0 and method.token_stream then -%>
             <div class="method-controls">
-              <details class="method-click-advice">
+              <details class="method-source-toggle">
                 <summary>Source</summary>
               </details>
             </div>
@@ -127,7 +127,7 @@
             <span class="method-args"><%= h method.param_seq %></span>
             <%- if method.token_stream then -%>
             <div class="method-controls">
-              <details class="method-click-advice">
+              <details class="method-source-toggle">
                 <summary>Source</summary>
               </details>
             </div>
diff --git a/lib/rdoc/generator/template/darkfish/css/rdoc.css b/lib/rdoc/generator/template/darkfish/css/rdoc.css
index 21d2e961f5..34a1fbd5b5 100644
--- a/lib/rdoc/generator/template/darkfish/css/rdoc.css
+++ b/lib/rdoc/generator/template/darkfish/css/rdoc.css
@@ -626,7 +626,7 @@ main .method-heading :link,
 main .method-heading :visited {
   color: inherit;
 }
-main .method-click-advice {
+main .method-source-toggle {
   position: absolute;
   top: 2px;
   right: 0px;
@@ -743,7 +743,7 @@ main .attribute-access-type {
     position: static;
   }
 
-  main .method-click-advice {
+  main .method-source-toggle {
     position: static;
     display: inline-block;
   }
diff --git a/lib/rdoc/generator/template/darkfish/js/darkfish.js b/lib/rdoc/generator/template/darkfish/js/darkfish.js
index ad67b61656..aeb8526344 100644
--- a/lib/rdoc/generator/template/darkfish/js/darkfish.js
+++ b/lib/rdoc/generator/template/darkfish/js/darkfish.js
@@ -34,7 +34,7 @@ function showSource( e ) {
 };
 
 function hookSourceViews() {
-  document.querySelectorAll('.method-click-advice').forEach(function (codeObject) {
+  document.querySelectorAll('.method-source-toggle').forEach(function (codeObject) {
     codeObject.addEventListener('click', showSource);
   });
 };

From e0340469c4747ba28fa2618e6128cc457ff90b26 Mon Sep 17 00:00:00 2001
From: Stan Lo <stan.lo@shopify.com>
Date: Mon, 9 Sep 2024 00:13:32 +0100
Subject: [PATCH 5/9] 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.
---
 .../generator/template/darkfish/class.rhtml   | 50 ++++++++-----------
 .../generator/template/darkfish/css/rdoc.css  | 26 ++++------
 2 files changed, 32 insertions(+), 44 deletions(-)

diff --git a/lib/rdoc/generator/template/darkfish/class.rhtml b/lib/rdoc/generator/template/darkfish/class.rhtml
index 683b47cf51..26652cada9 100644
--- a/lib/rdoc/generator/template/darkfish/class.rhtml
+++ b/lib/rdoc/generator/template/darkfish/class.rhtml
@@ -101,41 +101,35 @@
       <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 -%>
-            <div class="method-controls">
-              <details class="method-source-toggle">
-                <summary>Source</summary>
-              </details>
-            </div>
+            <%- 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 -%>
-            <div class="method-controls">
-              <details class="method-source-toggle">
-                <summary>Source</summary>
-              </details>
+            <div class="method-heading">
+              <span class="method-name"><%= h method.name %></span>
+              <span class="method-args"><%= h method.param_seq %></span>
             </div>
-            <%- end -%>
-          </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 -%>
diff --git a/lib/rdoc/generator/template/darkfish/css/rdoc.css b/lib/rdoc/generator/template/darkfish/css/rdoc.css
index 34a1fbd5b5..e7185677b9 100644
--- a/lib/rdoc/generator/template/darkfish/css/rdoc.css
+++ b/lib/rdoc/generator/template/darkfish/css/rdoc.css
@@ -615,6 +615,10 @@ main .method-detail:target {
   border-left: 10px solid #f1edba;
 }
 
+main .method-header {
+  display: inline-block;
+}
+
 main .method-heading {
   position: relative;
   font-family: var(--font-code);
@@ -622,16 +626,10 @@ main .method-heading {
   font-weight: bold;
   color: var(--text-color);
 }
-main .method-heading :link,
-main .method-heading :visited {
-  color: inherit;
-}
-main .method-source-toggle {
-  position: absolute;
-  top: 2px;
-  right: 0px;
-  padding-right: 20px;
+
+main .method-controls {
   line-height: 20px;
+  float: right;
   color: var(--secondary-color);
   cursor: pointer;
 }
@@ -739,13 +737,9 @@ main .attribute-access-type {
     white-space: nowrap;
   }
 
-  .method-controls {
-    position: static;
-  }
-
-  main .method-source-toggle {
-    position: static;
-    display: inline-block;
+  main .method-controls {
+    margin-top: 10px;
+    float: none;
   }
 }
 /* @end */

From 58dfe05ef53d42a347fd68b52670af60a5bfd7d6 Mon Sep 17 00:00:00 2001
From: Stan Lo <stan.lo@shopify.com>
Date: Thu, 12 Sep 2024 13:14:02 +0100
Subject: [PATCH 6/9] 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.
---
 .../generator/template/darkfish/css/rdoc.css   | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/lib/rdoc/generator/template/darkfish/css/rdoc.css b/lib/rdoc/generator/template/darkfish/css/rdoc.css
index e7185677b9..8e35782c12 100644
--- a/lib/rdoc/generator/template/darkfish/css/rdoc.css
+++ b/lib/rdoc/generator/template/darkfish/css/rdoc.css
@@ -601,6 +601,24 @@ main .method-source-code.active-menu {
   max-height: 100vh;
 }
 
+main pre.ruby::before {
+  content: "Example";
+  color: var(--secondary-color);
+  border-bottom: 1px solid var(--border-color);
+  display: block;
+  padding: 10px 0;
+  font-size: 0.9em;
+  margin-bottom: 10px;
+}
+
+main pre.ruby {
+  margin: 0;
+  padding: 0px 16px 16px 16px;
+  overflow-x: auto;
+  border-radius: 4px;
+  border-color: var(--border-color);
+}
+
 main .method-description .method-calls-super {
   color: var(--text-color);
   font-weight: bold;

From ae94708990233c012a731a07c604c016f525bf82 Mon Sep 17 00:00:00 2001
From: Stan Lo <stan.lo@shopify.com>
Date: Thu, 3 Oct 2024 12:26:34 +0100
Subject: [PATCH 7/9] Revert "Add "Example" label to example code blocks"

This reverts commit 69fc9ce6a379e3c28020b8e9b849b7c39948b848.
---
 .../generator/template/darkfish/css/rdoc.css   | 18 ------------------
 1 file changed, 18 deletions(-)

diff --git a/lib/rdoc/generator/template/darkfish/css/rdoc.css b/lib/rdoc/generator/template/darkfish/css/rdoc.css
index 8e35782c12..e7185677b9 100644
--- a/lib/rdoc/generator/template/darkfish/css/rdoc.css
+++ b/lib/rdoc/generator/template/darkfish/css/rdoc.css
@@ -601,24 +601,6 @@ main .method-source-code.active-menu {
   max-height: 100vh;
 }
 
-main pre.ruby::before {
-  content: "Example";
-  color: var(--secondary-color);
-  border-bottom: 1px solid var(--border-color);
-  display: block;
-  padding: 10px 0;
-  font-size: 0.9em;
-  margin-bottom: 10px;
-}
-
-main pre.ruby {
-  margin: 0;
-  padding: 0px 16px 16px 16px;
-  overflow-x: auto;
-  border-radius: 4px;
-  border-color: var(--border-color);
-}
-
 main .method-description .method-calls-super {
   color: var(--text-color);
   font-weight: bold;

From 87c4307a9b11018c2c993433b4db4aba3816224d Mon Sep 17 00:00:00 2001
From: Stan Lo <stan.lo@shopify.com>
Date: Thu, 3 Oct 2024 12:34:19 +0100
Subject: [PATCH 8/9] Give source code blocks a different background color

---
 lib/rdoc/generator/template/darkfish/css/rdoc.css | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/lib/rdoc/generator/template/darkfish/css/rdoc.css b/lib/rdoc/generator/template/darkfish/css/rdoc.css
index e7185677b9..a44383d485 100644
--- a/lib/rdoc/generator/template/darkfish/css/rdoc.css
+++ b/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;
@@ -596,6 +597,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;

From fd9fbcf4604a7737ff6fe6e538fa10f3be05d541 Mon Sep 17 00:00:00 2001
From: Stan Lo <stan.lo@shopify.com>
Date: Thu, 3 Oct 2024 17:10:13 +0100
Subject: [PATCH 9/9] Change targeted method's highlighting color to work
 better with the new method source

---
 lib/rdoc/generator/template/darkfish/css/rdoc.css | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/lib/rdoc/generator/template/darkfish/css/rdoc.css b/lib/rdoc/generator/template/darkfish/css/rdoc.css
index a44383d485..c53cbd4082 100644
--- a/lib/rdoc/generator/template/darkfish/css/rdoc.css
+++ b/lib/rdoc/generator/template/darkfish/css/rdoc.css
@@ -617,7 +617,7 @@ main .method-detail {
 
 main .method-detail:target {
   margin-left: -10px;
-  border-left: 10px solid #f1edba;
+  border-left: 10px solid var(--source-code-background-color);
 }
 
 main .method-header {