From c5f0fe12859cd194f4df9ba2072f70228da2fcd5 Mon Sep 17 00:00:00 2001 From: Stan Lo Date: Thu, 10 Oct 2024 17:45:36 +0800 Subject: [PATCH] [ruby/rdoc] Improve method source toggling (https://github.com/ruby/rdoc/pull/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 https://github.com/ruby/rdoc/commit/69fc9ce6a379. * Give source code blocks a different background color * Change targeted method's highlighting color to work better with the new method source https://github.com/ruby/rdoc/commit/e608a84af3 --- .../generator/template/darkfish/class.rhtml | 55 ++++++++++--------- .../generator/template/darkfish/css/rdoc.css | 38 +++++++------ .../template/darkfish/js/darkfish.js | 2 +- 3 files changed, 49 insertions(+), 46 deletions(-) diff --git a/lib/rdoc/generator/template/darkfish/class.rhtml b/lib/rdoc/generator/template/darkfish/class.rhtml index 6c64ba6c98..26652cada9 100644 --- a/lib/rdoc/generator/template/darkfish/class.rhtml +++ b/lib/rdoc/generator/template/darkfish/class.rhtml @@ -101,35 +101,42 @@
">
<%- if (call_seq = method.call_seq) then -%> - <%- call_seq.strip.split("\n").each_with_index do |call_seq, i| -%> -
- - <%= h(call_seq.strip. - gsub( /^\w+\./m, '')). - gsub(/(.*)[-=]>/, '\1→') %> - - <%- if i == 0 and method.token_stream then -%> - click to toggle source + <%- call_seq.strip.split("\n").each_with_index do |call_seq, i| -%> +
+ + <%= h(call_seq.strip. + gsub( /^\w+\./m, '')). + gsub(/(.*)[-=]>/, '\1→') %> + +
<%- end -%> -
- <%- end -%> <%- elsif method.has_call_seq? then -%> -
- <%= h method.name %> -
+
+ <%= h method.name %> +
<%- else -%> -
- <%= h method.name %><%= h method.param_seq %> - <%- if method.token_stream then -%> - click to toggle source - <%- end -%> -
+
+ <%= h method.name %> + <%= h method.param_seq %> +
<%- end -%>
+ <%- if method.token_stream -%> +
+
+ Source +
+
+ <%- end -%> + <%- unless method.skip_description? then -%>
+ <%- if method.token_stream then -%> +
+ 
<%= method.markup_code %>
+
+ <%- end -%> <%- if method.comment then -%> <%= method.description.strip %> <%- else -%> @@ -144,12 +151,6 @@ %>
<%- end -%> - - <%- if method.token_stream then -%> -
- 
<%= method.markup_code %>
-
- <%- end -%>
<%- end -%> diff --git a/lib/rdoc/generator/template/darkfish/css/rdoc.css b/lib/rdoc/generator/template/darkfish/css/rdoc.css index 772a06b85b..8b7662c645 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; @@ -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 */ diff --git a/lib/rdoc/generator/template/darkfish/js/darkfish.js b/lib/rdoc/generator/template/darkfish/js/darkfish.js index bea0a5f1cb..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-heading').forEach(function (codeObject) { + document.querySelectorAll('.method-source-toggle').forEach(function (codeObject) { codeObject.addEventListener('click', showSource); }); };