Improving the D documentation web presentation

Wed May 27 12:55:07 UTC 2020

On Wednesday, 27 May 2020 at 09:51:16 UTC, aberba wrote:
> [...]
>
> dpldocs is functionally the best. Not aesthetics though :). If 
> we could give it the ddoc look and feel, that'll be complete.

I tinkered a little bit with the HTML and CSS of dpldocs, here 
are some changes I made:

Screenshots:

Before:
https://i.imgur.com/bQ60YWA.png
After:
https://i.imgur.com/hJOGhrR.png

Before:
https://i.imgur.com/i2tow79.png
After:
https://i.imgur.com/JKingMa.png

Module:
https://i.imgur.com/PmJlkoo.png

I didn't touch the headerbar, I think the design should just be 
copied from the homepage there.

HTML changes:

- Added a span inside the h1 title with class .name
- Prepended the symbol kind as text to the title ("Function")
- Add `lang="en"` to <html>
	JS code to preview this: 
document.body.parentElement.setAttribute("lang", "en")
- In the Parameters section move all the types into the parameter 
names
	JS code to preview this: 
document.querySelectorAll(".parameter-descriptions 
dt").forEach(dt => 
dt.appendChild(dt.nextElementSibling.querySelector(".parameter-type")))
- Delete the empty parameter type holders
	JS code to preview this: 
document.querySelectorAll(".parameter-type-holder:empty").forEach(a => a.parentElement.removeChild(a))
- In the Parameters section delete the "Type:" string for each 
argument
	JS code to preview this: 
document.querySelectorAll(".parameter-descriptions 
.parameter-type-holder").forEach(t => 
t.removeChild(t.childNodes[0]));
- for each pre.d_code.highlighted, insert a <header> tag before 
it, move the "Copy to Clipboard" and "Toggle Line Numbers" 
buttons into the header tag, wrap everything in a <div 
class="codeblock">
	JS code to preview this: 
document.querySelectorAll("pre.d_code.highlighted").forEach(c=>{c.parentElement.insertBefore(h=document.createElement("header"),c);while(b=h.previousElementSibling,b.tagName=="BUTTON")h.prepend(b);h.parentElement.insertBefore(w=document.createElement("div"),h);w.className="codeblock";w.appendChild(h);w.appendChild(c)})
- Disable Line numbers by default for short code (<15 lines)
- Delete & Disable the dynamic style (resize style)
	JS code to preview this: window.onresize = undefined; var d = 
document.querySelector("#dynamic-style"); 
d.parentElement.removeChild(d);
- In the small overloads buttons (.overloads>li 
.overload-signature), remove all parameter type qualifiers and 
default values, only keep names and basic types

Quick apply JS:
// manually add function kind & span.name
// manually disable line numbers in short code blocks
// manually edit overload buttons to only have argument types & 
names
document.body.parentElement.setAttribute("lang", "en")
document.querySelectorAll(".parameter-descriptions 
dt").forEach(dt => 
dt.appendChild(dt.nextElementSibling.querySelector(".parameter-type")))
document.querySelectorAll(".parameter-type-holder:empty").forEach(a => a.parentElement.removeChild(a))
document.querySelectorAll(".parameter-descriptions 
.parameter-type-holder").forEach(t => 
t.removeChild(t.childNodes[0]));
document.querySelectorAll("pre.d_code.highlighted").forEach(c=>{c.parentElement.insertBefore(h=document.createElement("header"),c);while(b=h.previousElementSibling,b.tagName=="BUTTON")h.prepend(b);h.parentElement.insertBefore(w=document.createElement("div"),h);w.className="codeblock";w.appendChild(h);w.appendChild(c)})
window.onresize = undefined; var d = 
document.querySelector("#dynamic-style"); 
d.parentElement.removeChild(d);

Additional work to be done:

Make link for `const(char)[]` as type explaining that it works 
with strings and char arrays. Also embed the graph from and link 
to 
https://dlang.org/spec/const3.html#implicit_qualifier_conversions

Make link for `size_t` and `ptrdiff_t` as type explaining that 
it's an (unsigned) integer type, commonly (u)int or (u)long with 
link to https://dlang.org/spec/type.html#size_t

CSS additions:

#page-body #page-content {
   padding-left: 1.75em;
}

#page-content h1:first-child {
   margin-top: 2rem;
   font-size: 2.2rem;
   font-family: "Roboto Slab", sans-serif;
   font-weight: normal;
   margin-bottom: 0.5rem;
}

#page-content h1:first-child + .breadcrumbs {
   margin-top: 0;
}

#page-content h1 .name {
   font-family: Consolas, "Bitstream Vera Sans Mono", "Andale 
Mono", Monaco, "DejaVu Sans Mono", "Lucida Console", monospace;
}

#page-content h2,
#page-content h3 {
   margin-top: 1.5em;
   font-family: "Roboto Slab", sans-serif;
   font-weight: normal;
}

#page-content h2 {
   font-size: 1.6rem;
}

#page-content h3 {
   font-size: 1.26rem;
}

#table-of-contents, .enum-members, .documentation-comment .tip, 
.documentation-comment .note, .documentation-comment .warning, 
.documentation-comment .pitfall, .documentation-comment li, 
.documentation-comment p {
   font-size: 1rem;
}

#page-body #page-nav {
   padding-left: 1em;
   padding-right: 0;
   border-left-style: solid;
   border-left-width: 1px;
   overflow: unset;
}

#page-nav ul {
   list-style: none;
}

#page-nav .type-separator {
   margin-bottom: 0.25em;
}

#page-nav a {
   box-sizing: border-box;
   font-family: "Roboto Slab", sans-serif;
   padding: 1pt 0.25em 1pt 0.5em;
   text-overflow: ellipsis;
   overflow: hidden;
}

#page-nav a:hover {
   position: relative;
   overflow: visible;
   z-index: 10;
   background-color: rgb(245, 245, 245);
   width: max-content;
}

#page-nav a.parent {
   line-height: 0.9;
   overflow: visible;
}

#page-nav a.parent:first-child {
   margin-top: 0.75em;
}

tt.D, .inline-code, .parameter-descriptions .parameter-name {
   color: black;
	font-weight: 500;
	background-color: #f2f2f2;
	padding: 0px 0.5ex;
   border-radius: 2px;
}

.parameter-descriptions .parameter-name {
   margin-right: 1.5rem;
   font-weight: bold;
	padding: 0.25ex 0.75ex;
}

.parameter-descriptions dd {
   margin-left: 1.5em;
}

.parameter-descriptions dd p:first-child {
   margin-top: 0.5em;
}

.parameter-descriptions dt:not(:first-child) {
   margin-top: 1.5em;
}

.codeblock {
   border: solid 1px #ccc;
   padding: 0;
   margin: 0;
}

.codeblock header {
   background-color: #e8e8e8;
   padding: 0;
   display: flex;
   justify-content: flex-end;
}

.codeblock header:before {
   display: inline-block;
   content: "Example";
   justify-content: flex-start;
   flex-grow: 1;
   padding: 0.25em 1em;
   font-weight: bold;
}

.codeblock header button {
/*  TODO: add :before class with icons here (copy, line numbers)  
*/
   appearance: none;
   -webkit-appearance: none;
   -moz-appearance: none;
   margin: 0;
   padding: 0 1em;
   background-color: transparent;
   border: none;
   border-left: 1px solid #ccc;
   cursor: pointer;
}

.codeblock header button:hover {
   background-color: rgba(255, 255, 255, 0.5);
}

.codeblock pre.d_code {
   border: none;
   border-top: solid 1px #ccc;
   margin: 0;
   padding: 1em 0;
   max-width: unset !important;;
}

.hide-line-numbers .codeblock .with-line-wrappers,
.codeblock pre.d_code:not(.with-line-wrappers) {
   padding: 1em;
}

.codeblock .with-line-wrappers .br {
   margin-right: 1em;
}

.annotated-prototype .overloads li {
   margin: 0;
}

.member-list .dt, .overload-option, pre {
   max-width: unset;
}

.documentation-comment p {
   hyphens: auto;
}

.declaration-prototype, .aggregate-prototype, .function-prototype 
{
   margin-left: 0;
   margin-right: 0;
}