Merge pull request #356 from jonathanhefner/constants-redesign

Redesign "Constants" section
rails · Jan 4, 2024 · d26434f · d26434f
2 parents 7e67807 + addb4cd
commit d26434f
Show file tree

Hide file tree

Showing 5 changed files with 55 additions and 46 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -36,6 +36,7 @@ Main (3.0.0.alpha)
 * [#322](https://github.com/rails/sdoc/pull/322) Use `type="search"` for search input [@jonathanhefner](https://github.com/jonathanhefner)
 * [#323](https://github.com/rails/sdoc/pull/323) Update favicon [@jonathanhefner](https://github.com/jonathanhefner)
 * [#345](https://github.com/rails/sdoc/pull/345) Version explicit links to `api.rubyonrails.org` [@jonathanhefner](https://github.com/jonathanhefner)
+* [#356](https://github.com/rails/sdoc/pull/356) Redesign "Constants" section [@jonathanhefner](https://github.com/jonathanhefner)
 
 2.6.1
 =====

diff --git a/lib/rdoc/generator/template/rails/_context.rhtml b/lib/rdoc/generator/template/rails/_context.rhtml
@@ -54,27 +54,22 @@
 
     <%= description_for section %>
 
+    <!-- Constants -->
     <% unless constants.empty? %>
-      <!-- Section constants -->
       <h2 class="content__divider">Constants</h2>
-      <table border='0' cellpadding='5'>
-        <% constants.each do |const| %>
-          <tr valign='top'>
-            <td class="attr-name"><%= short_name_for const %></td>
-            <td>=</td>
-            <td class="attr-value"><%= h const.value %></td>
-          </tr>
-          <% if const.comment && !const.comment.empty? %>
-            <tr valign='top'>
-              <td>&nbsp;</td>
-              <td colspan="2" class="attr-desc"><%= const.description.strip %></td>
-            </tr>
-          <% end %>
-        <% end %>
-      </table>
+      <% constants.each do |constant| %>
+        <div class="constant">
+          <div class="constant__name">
+            <h3><%= short_name_for constant %></h3>
+          </div>
+          <%= description_for constant %>
+          <div class="constant__source">
+            <pre class="source-code"><code class="ruby"><%= h constant.value %></code></pre>
+          </div>
+        </div>
+      <% end %>
     <% end %>
 
-
     <% unless attributes.empty? %>
       <!-- Section attributes -->
       <h2 class="content__divider">Attributes</h2>
@@ -135,7 +130,7 @@
                 <% end %>
               </summary>
 
-              <pre><code class="ruby"><%= source_code %></code></pre>
+              <pre class="source-code"><code class="ruby"><%= source_code %></code></pre>
             </details>
           <% elsif source_url %>
             <p class="method__source"><%= link_to_external "GitHub", source_url %></p>

diff --git a/lib/rdoc/generator/template/rails/resources/css/main.css b/lib/rdoc/generator/template/rails/resources/css/main.css
@@ -289,21 +289,25 @@ th
   font-style: italic;
 }
 
-.description pre, .method__source pre {
+.description pre, pre.source-code {
   padding: 0.5ch 1ch;
   border-radius: 6px;
   overflow-x: auto;
-
-  background: var(--code-bg);
 }
 
-
 :is(.description p, p.description) code {
-  background: var(--code-bg);
   padding: 0 0.15em;
   border-radius: 3px;
 }
 
+.description pre, :is(.description p, p.description) code {
+  background: var(--code-bg);
+}
+
+pre.source-code {
+  background: var(--source-code-bg);
+}
+
 @media (hover: hover) {
   .description a:hover code {
     box-shadow: 0 0 0 1px;
@@ -737,11 +741,35 @@ html {
   border-bottom: 1px solid;
 }
 
-.content__section-title + .content__divider {
+.content__section-title + .content__divider,
+.content__divider + :is(*, div /* increase selector specificity */) {
   margin-top: var(--space);
 }
 
 
+/*
+ * Constant
+ */
+
+.constant {
+  margin-top: var(--space-lg);
+}
+
+.constant__name {
+  padding-bottom: var(--space-xs);
+  border-bottom: 2px solid var(--code-bg);
+}
+
+.constant__name code {
+  font-size: 1rem;
+  font-weight: bold;
+}
+
+.constant__name + *, .constant__source {
+  margin-top: var(--space-sm);
+}
+
+
 /*
  * Method
  */
@@ -750,10 +778,6 @@ html {
   margin-top: var(--space-xl);
 }
 
-.content__divider + .method {
-  margin-top: var(--space);
-}
-
 
 .method__signature {
   padding-bottom: var(--space-xs);
@@ -847,7 +871,6 @@ html {
 
 .method__source pre {
   margin-top: var(--space-xs);
-  background: var(--source-code-bg);
 }
 
 

diff --git a/lib/sdoc/postprocessor.rb b/lib/sdoc/postprocessor.rb
@@ -92,7 +92,7 @@ def unify_h1_headings!(document)
   end
 
   def highlight_code_blocks!(document)
-    document.css(".description pre > code, .method__source pre > code").each do |element|
+    document.css(".description pre > code, pre.source-code > code").each do |element|
       code = element.inner_text
       language = element.classes.include?("ruby") ? "ruby" : guess_code_language(code)
       element.inner_html = highlight_code(code, language)

diff --git a/spec/postprocessor_spec.rb b/spec/postprocessor_spec.rb
@@ -151,7 +151,7 @@
       _(SDoc::Postprocessor.process(rendered)).must_include rendered
     end
 
-    it "highlights code blocks" do
+    it "highlights description code blocks" do
       rendered = <<~HTML
         <div class="description">
           <p>Ruby:</p>
@@ -173,25 +173,15 @@
       _(SDoc::Postprocessor.process(rendered)).must_include expected
     end
 
-    it "highlights method source code" do
+    it "highlights source code blocks" do
       rendered = <<~HTML
-        <div class="method__source">
-          <pre><code class="ruby"><span class="ruby-comment"># highlighted by RDoc</span></code></pre>
-        </div>
-
-        <div class="method__source">
-          <pre><code class="ruby">DELETE FROM 'tricky_ruby'</code></pre>
-        </div>
+        <pre class="source-code"><code class="ruby"><span class="ruby-comment"># highlighted by RDoc</span></code></pre>
+        <pre class="source-code"><code class="ruby">DELETE FROM 'tricky_ruby'</code></pre>
       HTML
 
       expected = <<~HTML
-        <div class="method__source">
-          <pre><code class="ruby highlight">#{SDoc::Postprocessor.highlight_code("# highlighted by RDoc", "ruby")}</code></pre>
-        </div>
-
-        <div class="method__source">
-          <pre><code class="ruby highlight">#{SDoc::Postprocessor.highlight_code("DELETE FROM 'tricky_ruby'", "ruby")}</code></pre>
-        </div>
+        <pre class="source-code"><code class="ruby highlight">#{SDoc::Postprocessor.highlight_code("# highlighted by RDoc", "ruby")}</code></pre>
+        <pre class="source-code"><code class="ruby highlight">#{SDoc::Postprocessor.highlight_code("DELETE FROM 'tricky_ruby'", "ruby")}</code></pre>
       HTML
 
       _(SDoc::Postprocessor.process(rendered)).must_include expected