Skip to content

Commit

Permalink
Refactor docs generator HTML scaffold (#5816)
Browse files Browse the repository at this point in the history 
* 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.
  • Loading branch information
@straight-shoota
straight-shoota authored and Serdar Dogruyol committed Apr 13, 2018
1 parent 9df0315 commit 90c3a7a
Show file tree
Hide file tree
Showing 12 changed files with 99 additions and 86 deletions.
6 changes: 6 additions & 0 deletions src/compiler/crystal/tools/doc/html/_head.html
View file
@@ -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>
0 ...er/crystal/tools/doc/html/list_items.html → ...r/crystal/tools/doc/html/_list_items.html
View file
File renamed without changes.
0 ...crystal/tools/doc/html/method_detail.html → ...rystal/tools/doc/html/_method_detail.html
View file
File renamed without changes.
0 ...rystal/tools/doc/html/method_summary.html → ...ystal/tools/doc/html/_method_summary.html
View file
File renamed without changes.
0 ...tal/tools/doc/html/methods_inherited.html → ...al/tools/doc/html/_methods_inherited.html
View file
File renamed without changes.
0 ...r/crystal/tools/doc/html/other_types.html → .../crystal/tools/doc/html/_other_types.html
View file
File renamed without changes.
19 changes: 19 additions & 0 deletions src/compiler/crystal/tools/doc/html/_sidebar.html
View file
@@ -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>
88 changes: 50 additions & 38 deletions src/compiler/crystal/tools/doc/html/css/style.css
View file
Expand Up @@ -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;
Expand All @@ -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;
Expand All @@ -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 {
Expand Down Expand Up @@ -487,6 +498,7 @@ span.flag.purple {
}
.search-results .search-result__title > a {
padding: 0;
display: block;
}
.search-result__title > a > .args {
color: #dddddd;
Expand Down Expand Up @@ -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 {
Expand Down
10 changes: 5 additions & 5 deletions src/compiler/crystal/tools/doc/html/js/doc.js
View file
Expand Up @@ -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);
Expand Down Expand Up @@ -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;
Expand Down
22 changes: 3 additions & 19 deletions src/compiler/crystal/tools/doc/html/main.html
View file
@@ -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>
Expand Down
22 changes: 3 additions & 19 deletions src/compiler/crystal/tools/doc/html/type.html
View file
@@ -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 %>
Expand Down
18 changes: 13 additions & 5 deletions src/compiler/crystal/tools/doc/templates.cr
View file
Expand Up @@ -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
Expand Down

0 comments on commit 90c3a7a

Please sign in to comment.