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.
straight-shoota authored and sdogruyol committed Apr 13, 2018
1 parent 9df0315 commit 90c3a7a
Showing 12 changed files with 99 additions and 86 deletions.
6 changes: 6 additions & 0 deletions src/compiler/crystal/tools/doc/html/_head.html
Original file line number Diff line number Diff line change
@@ -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>
19 changes: 19 additions & 0 deletions src/compiler/crystal/tools/doc/html/_sidebar.html
Original file line number Diff line number Diff line change
@@ -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
Original file line number Diff line number Diff line change
@@ -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 {
10 changes: 5 additions & 5 deletions src/compiler/crystal/tools/doc/html/js/doc.js
Original file line number Diff line number Diff line change
@@ -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;
22 changes: 3 additions & 19 deletions src/compiler/crystal/tools/doc/html/main.html
Original file line number Diff line number Diff line change
@@ -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>
22 changes: 3 additions & 19 deletions src/compiler/crystal/tools/doc/html/type.html
Original file line number Diff line number Diff line change
@@ -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 %>
18 changes: 13 additions & 5 deletions src/compiler/crystal/tools/doc/templates.cr
Original file line number Diff line number Diff line change
@@ -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

0 comments on commit 90c3a7a

Please sign in to comment.