Refactor docs generator HTML scaffold (#5816)

* Rename partial templates with leading underscore

* Add _head.html partial to dry up html head

* Add _sidebar.html partial, remove style IDs and use flexbox

This dries up sidebar code.
Element IDs for CSS selectors are replaced with classes to reduce specificity in
stylesheets (avoid specificity wars).
Flexbox is better than absolute positioning as it allows for more
flexible layout and dimensions.

Author: straight-shoota

src/compiler/crystal/tools/doc/html/_head.html

@@ -0,0 +1,6 @@
+<meta charset="utf-8" />
+<meta http-equiv="X-UA-Compatible" content="IE=edge">
+<meta name="generator" content="Crystal Docs <%= Crystal::VERSION %>">
+
+<link href="<%= base_path %>css/style.css" rel="stylesheet" type="text/css" />
+<script type="text/javascript" src="<%= base_path %>js/doc.js"></script>

src/compiler/crystal/tools/doc/html/list_items.html src/compiler/crystal/tools/doc/html/_list_items.html

@@ -0,0 +1,19 @@
+<div class="sidebar">
+  <div class="sidebar-header">
+    <div class="search-box">
+      <input type="search" class="search-input" placeholder="Search..." spellcheck="false">
+    </div>
+
+    <div class="repository-links">
+      <a href="<%= current_type.try(&.path_to("")) %>index.html">README</a>
+    </div>
+  </div>
+
+  <div class="search-results" class="hidden">
+    <ul class="search-list"></ul>
+  </div>
+
+  <div class="types-list">
+    <%= ListItemsTemplate.new(types, current_type) %>
+  </div>
+</div>

src/compiler/crystal/tools/doc/html/method_detail.html src/compiler/crystal/tools/doc/html/_method_detail.html

@@ -40,26 +40,28 @@ h2 {
   padding-bottom: 5px;
 }
 
-#types-list, #main-content {
-  position: absolute;
-  top: 0;
-  bottom: 0;
+body {
+  display: flex;
+}
+
+.sidebar, .main-content {
   overflow: auto;
 }
 
-#types-list {
-  left: 0;
-  width: 20%;
+.sidebar {
+  width: 30em;
+  color: #F8F4FD;
   background-color: #2E1052;
   padding: 0 0 30px;
   box-shadow: inset -3px 0 4px rgba(0,0,0,.35);
+  line-height: 1.2;
 }
 
-#types-list #search-box {
+.sidebar .search-box {
   padding: 8px 9px;
 }
 
-#types-list input {
+.sidebar input {
   display: block;
   box-sizing: border-box;
   margin: 0;
@@ -75,82 +77,92 @@ h2 {
   transition: box-shadow .12s;
 }
 
-#types-list input:focus {
+.sidebar input:focus {
   box-shadow: 0px 5px 6px rgba(0,0,0,.5);
 }
 
-#types-list input::-webkit-input-placeholder { /* Chrome/Opera/Safari */
+.sidebar input::-webkit-input-placeholder { /* Chrome/Opera/Safari */
   color: #C8C8C8;
   font-size: 14px;
   text-indent: 2px;
 }
 
-#types-list input::-moz-placeholder { /* Firefox 19+ */
+.sidebar input::-moz-placeholder { /* Firefox 19+ */
   color: #C8C8C8;
   font-size: 14px;
   text-indent: 2px;
 }
 
-#types-list input:-ms-input-placeholder { /* IE 10+ */
+.sidebar input:-ms-input-placeholder { /* IE 10+ */
   color: #C8C8C8;
   font-size: 14px;
   text-indent: 2px;
 }
 
-#types-list input:-moz-placeholder { /* Firefox 18- */
+.sidebar input:-moz-placeholder { /* Firefox 18- */
   color: #C8C8C8;
   font-size: 14px;
   text-indent: 2px;
 }
 
-#types-list ul {
+.sidebar ul {
   margin: 0;
   padding: 0;
   list-style: none outside;
 }
 
-#types-list li {
+.sidebar li {
   display: block;
   position: relative;
 }
 
-#types-list li.hide {
+.types-list li.hide {
   display: none;
 }
 
-#types-list a,
-.search_result .search-result__title > a {
-  display: block;
+.sidebar a {
   text-decoration: none;
-  color: #F8F4FD;
+  color: inherit;
   transition: color .14s;
 }
 .types-list a {
+  display: block;
   padding: 5px 15px 5px 30px;
 }
 
-#types-list a:focus {
+.types-list {
+  display: block;
+}
+
+.sidebar a:focus {
   outline: 1px solid #D1B7F1;
 }
 
-#types-list .current > a,
-#types-list a:hover {
+.types-list a {
+  padding: 5px 15px 5px 30px;
+}
+
+.sidebar .current > a,
+.sidebar a:hover {
   color: #866BA6;
 }
 
-#types-list li ul {
+.repository-links {
+  padding: 5px 15px 5px 30px;
+}
+
+.types-list li ul {
   overflow: hidden;
   height: 0;
   max-height: 0;
   transition: 1s ease-in-out;
 }
 
-
-#types-list li.parent {
+.types-list li.parent {
   padding-left: 30px;
 }
 
-#types-list li.parent::before {
+.types-list li.parent::before {
   box-sizing: border-box;
   content: "▼";
   display: block;
@@ -169,23 +181,22 @@ h2 {
 }
 
 
-#types-list li.parent > a {
+.types-list li.parent > a {
   padding-left: 0;
 }
 
-#types-list li.parent.open::before {
+.types-list li.parent.open::before {
   transform: rotateZ(0);
 }
 
-#types-list li.open > ul {
+.types-list li.open > ul {
   height: auto;
   max-height: 1000em;
 }
 
-#main-content {
+.main-content {
   padding: 0 30px 30px 30px;
-  left: 20%;
-  right: 0;
+  width: 100%;
 }
 
 .kind {
@@ -487,6 +498,7 @@ span.flag.purple {
 }
 .search-results .search-result__title > a {
   padding: 0;
+  display: block;
 }
 .search-result__title > a > .args {
   color: #dddddd;
@@ -536,13 +548,13 @@ span.flag.purple {
 .js-modal-visible .modal-background {
   display: flex;
 }
-#types-list,
-#main-content {
+.types-list,
+.main-content {
   filter: blur(0);
   transition: filter 200ms;
 }
-.js-modal-visible #types-list,
-.js-modal-visible #main-content {
+.js-modal-visible .types-list,
+.js-modal-visible .main-content {
   filter: blur(2px);
 }
 .modal-background {

src/compiler/crystal/tools/doc/html/method_summary.html src/compiler/crystal/tools/doc/html/_method_summary.html

@@ -19,10 +19,10 @@ document.addEventListener('DOMContentLoaded', function() {
     };
   }
 
-  var repositoryName = document.getElementById('repository-name').getAttribute('content');
-  var typesList = document.getElementById('types-list');
-  var searchInput = document.getElementById('search-input');
-  var parents = document.querySelectorAll('#types-list li.parent');
+  var repositoryName = document.querySelector('#repository-name').getAttribute('content');
+  var typesList = document.querySelector('.types-list');
+  var searchInput = document.querySelector('.search-input');
+  var parents = document.querySelectorAll('.types-list li.parent');
 
   var setPersistentSearchQuery = function(value){
     sessionStorage.setItem(repositoryName + '::search-input:value', value);
@@ -56,7 +56,7 @@ document.addEventListener('DOMContentLoaded', function() {
     window.focus();
   }
 
-  var navigator = new Navigator(document.querySelector('#types-list'), searchInput, document.querySelector(".search-results"), leaveSearchScope);
+  var navigator = new Navigator(document.querySelector('.types-list'), searchInput, document.querySelector(".search-results"), leaveSearchScope);
 
   CrystalDoc.loadIndex();
   var searchTimeout;

src/compiler/crystal/tools/doc/html/methods_inherited.html src/compiler/crystal/tools/doc/html/_methods_inherited.html

@@ -1,34 +1,18 @@
 <!DOCTYPE html>
 <html lang="en">
 <head>
-  <meta charset="utf-8" />
+  <%= HeadTemplate.new("") %>
   <meta id="repository-name" content="<%= repository_name %>">
-  <link href="css/style.css" rel="stylesheet" type="text/css" />
-  <script type="text/javascript" src="js/doc.js"></script>
   <title>README - <%= repository_name %></title>
   <script type="text/javascript">
   CrystalDoc.base_path = "";
   </script>
 </head>
 <body>
 
-<div id="types-list">
-  <div id="search-box">
-    <input type="search" id="search-input" placeholder="Search..." spellcheck="false">
-  </div>
+<%= SidebarTemplate.new(repository_name, types, nil) %>
 
-  <a href="index.html">README</a>
-
-  <div class="search-results" class="hidden">
-    <ul class="search-list"></ul>
-  </div>
-
-  <div class="types-list">
-    <%= ListItemsTemplate.new(types, nil) %>
-  </div>
-</div>
-
-<div id="main-content">
+<div class="main-content">
 <%= body %>
 </div>
 </body>

src/compiler/crystal/tools/doc/html/other_types.html src/compiler/crystal/tools/doc/html/_other_types.html

@@ -1,34 +1,18 @@
 <!DOCTYPE html>
 <html lang="en">
 <head>
-  <meta charset="utf-8" />
+  <%= HeadTemplate.new(type.path_to "") %>
   <meta id="repository-name" content="<%= type.repository_name %>">
-  <link href="<%= type.path_to "css/style.css" %>" rel="stylesheet" type="text/css" />
-  <script type="text/javascript" src="<%= type.path_to "js/doc.js" %>"></script>
   <title><%= type.full_name %> - <%= type.repository_name %></title>
   <script type="text/javascript">
     CrystalDoc.base_path = "<%= type.path_to "" %>";
   </script>
 </head>
 <body>
 
-<div id="types-list">
-  <div id="search-box">
-    <input type="search" id="search-input" placeholder="Search..." spellcheck="false">
-  </div>
+<%= SidebarTemplate.new(type.repository_name, types, type) %>
 
-  <a href="<%= type.path_to("index.html") %>">README</a>
-
-  <div class="search-results" class="hidden">
-    <ul class="search-list"></ul>
-  </div>
-
-  <div class="types-list">
-    <%= ListItemsTemplate.new(types, type) %>
-  </div>
-</div>
-
-<div id="main-content">
+<div class="main-content">
 <h1 class="type-name">
 <% if type.program? %>
   <%= type.full_name %>

src/compiler/crystal/tools/doc/html/_sidebar.html

@@ -6,29 +6,37 @@ module Crystal::Doc
   end
 
   record ListItemsTemplate, types : Array(Type), current_type : Type? do
-    ECR.def_to_s "#{__DIR__}/html/list_items.html"
+    ECR.def_to_s "#{__DIR__}/html/_list_items.html"
   end
 
   record MethodSummaryTemplate, title : String, methods : Array(Method) | Array(Macro) do
-    ECR.def_to_s "#{__DIR__}/html/method_summary.html"
+    ECR.def_to_s "#{__DIR__}/html/_method_summary.html"
   end
 
   record MethodDetailTemplate, title : String, methods : Array(Method) | Array(Macro) do
-    ECR.def_to_s "#{__DIR__}/html/method_detail.html"
+    ECR.def_to_s "#{__DIR__}/html/_method_detail.html"
   end
 
   record MethodsInheritedTemplate, type : Type, ancestor : Type, methods : Array(Method), label : String do
-    ECR.def_to_s "#{__DIR__}/html/methods_inherited.html"
+    ECR.def_to_s "#{__DIR__}/html/_methods_inherited.html"
   end
 
   record OtherTypesTemplate, title : String, type : Type, other_types : Array(Type) do
-    ECR.def_to_s "#{__DIR__}/html/other_types.html"
+    ECR.def_to_s "#{__DIR__}/html/_other_types.html"
   end
 
   record MainTemplate, body : String, types : Array(Type), repository_name : String do
     ECR.def_to_s "#{__DIR__}/html/main.html"
   end
 
+  record HeadTemplate, base_path : String do
+    ECR.def_to_s "#{__DIR__}/html/_head.html"
+  end
+
+  record SidebarTemplate, repository_name : String, types : Array(Type), current_type : Type? do
+    ECR.def_to_s "#{__DIR__}/html/_sidebar.html"
+  end
+
   struct JsTypeTemplate
     ECR.def_to_s "#{__DIR__}/html/js/doc.js"
   end