Skip to content

Commit

Permalink
Improve rendering of api docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@tafsiri
tafsiri authored Feb 14, 2018
1 parent 0c9f900 commit 97bc9dd
Show file tree
Hide file tree
Showing 2 changed files with 140 additions and 65 deletions.
197 changes: 136 additions & 61 deletions website/api/index.html
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
<head>
<script src="https://cdn.jsdelivr.net/npm/deeplearn@latest"></script>
<link rel="stylesheet" href="https://code.getmdl.io/1.3.0/material.cyan-teal.min.css" />
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/styles/solarized-dark.min.css">
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/styles/railscasts.min.css">
<meta name="viewport" content="width=device-width, initial-scale=1.0">

<style>
Expand Down Expand Up @@ -127,6 +127,16 @@
.toc a {
font-weight: normal;
text-decoration-color: lightgrey;
text-decoration: none;
transition-property: color, text-decoration-color, padding;
transition-duration: 0.15s;
}

.toc a.highlighted {
color: #0277BD;
text-decoration-color: #002b36;
padding-left: 6px;
font-weight: bold;
}

/* .toc::-webkit-scrollbar {
Expand Down Expand Up @@ -159,9 +169,16 @@

.reference .subsection-description {
font-weight: 300;
margin-bottom: 96px;
margin-bottom: 80px;
border-bottom: 1px solid rgb(96,125,139);
margin-left: 8px;
padding-bottom: 24px;
font-size: 21px;
}

.reference .subsection-description p {
font-size: inherit;
font-weight: inherit;
}

.reference .symbol-marker {
Expand All @@ -172,6 +189,12 @@
color: grey;
}

.reference .symbol-name {
text-decoration: none;
color: #0277BD;
margin-right: 0.33em;
}

.documentation pre, .param-docs pre {
background: #f4f4f4;
}
Expand All @@ -182,35 +205,35 @@
}

pre.hljs {
margin: 0;
margin: 24px;
/* margin-left: 24px; */
padding: 0;
}



code, .param-name, .return-type {
background: #f7f7f7;
background: #f4f4f4;
color: #37474f;
padding: 2px 4px;
font: 500 90%/2 Roboto Mono, monospace;
/* padding: 2px 4px; */
font-weight: 500;
font-family: Roboto Mono, monospace;
word-break: break-word;
}

.documentation a, .returns a, .param-name a, .method-docs a, .param-docs a {
background: #f4f4f4;
padding: 4px 6px;
font: 500 90%/2 Roboto Mono, monospace;
/* background: #f4f4f4; */
color: #0277BD;
/* padding: 2px 2px; */
font-weight: 500;
font-family: Roboto Mono, monospace;
}

.documentation {
white-space: pre;
}


.reference .symbol {
margin-left: 32px;
margin-bottom: 96px;
border-bottom: 1px dashed lightgrey;
border-bottom: 1px solid #0277BD;
padding-bottom: 16px;
}

Expand All @@ -222,9 +245,12 @@
margin-bottom: 8px;
}

.parameter-heading, .returns {
.parameter-heading, .returns-header {
margin-top: 8px;
font-weight: 500;
font-variant: small-caps;
text-transform: lowercase;
font-size: 16px;
}

.method {
Expand All @@ -239,10 +265,6 @@
padding: 4px 12px;
}

.method-name {
font-size: 20px;
}

.method-docs {
padding: 12px 0 0 16px;
}
Expand All @@ -253,21 +275,92 @@
}

.source-ref a {
color: #346f91
}

.mdl-chip__text {
vertical-align: baseline !important;
color:#0277BD;
}

.class-chip {
margin-left: 16px;
.chip {
background: #f4f4f4;
display: inline-block;
padding: 0 6px 0 6px;
border-radius: 4px;
font-weight: 500;
font-size: 82%;
}

</style>

<script>
document.addEventListener('DOMContentLoaded', function(e) {
// Find the symbol closest to the top of the page in the reference
// section and highlight it in the TOC section.

var refSymbols = document.querySelectorAll('.symbol-name');
var refArea = document.querySelector('.reference');
var tocArea = document.querySelector('.toc');

var lastHighlightedTocElement;

function updateTocView() {
var top = refArea && refArea.scrollTop

var found;
var tocFound;

for (var i = 0; i < refSymbols.length; i++) {
var symbol = refSymbols[i];
var sTop = symbol.offsetTop;
if (sTop > top) {
found = symbol;
break;
}
}

if (found) {
tocFound = tocArea.querySelector(`[href="#${found.getAttribute('name')}"]`)

if (lastHighlightedTocElement) {
lastHighlightedTocElement.classList.remove('highlighted');
}
tocFound.classList.add('highlighted');
tocFound.scrollIntoView(false);
lastHighlightedTocElement = tocFound;
}
}

refArea.addEventListener('scroll', updateTocView)
refArea.addEventListener('resize', updateTocView)
});
</script>
</head>

<body>
<!-- Partials -->
{{#*inline "paramList"}}
<div class="parameter-list">
<div class="parameter-heading">Parameters:</div>
<ul>
{{#parameters}}
<li class="parameter">
<span <span class="param-name">
{{name}}:&nbsp;{{{markdownInner type}}}
</span>
<span class="param-docs">
{{{markdownInner documentation}}}
</span>
{{#optional}}
<span class="chip">
Optional
</span>
{{/optional}}
</li>
{{/parameters}}
</ul>
</div>

{{/inline}}
<!-- END Partials -->


<div class="container">
<nav>
<a href="index.html">deeplearn.js</a>
Expand Down Expand Up @@ -307,33 +400,26 @@
{{#symbols}}
<div class="symbol">
<h5>
<span class='symbol-marker'>&fnof;</span>
<a name="{{urlHash}}" href="#{{urlHash}}">{{displayName}}</a>{{paramStr}}
{{#isClass}}
<span class="class-chip mdl-chip">
<span class="mdl-chip__text">Class</span>
</span>
{{/isClass}}
{{#if isClass}}
<span class="chip">Class</span>
{{else}}
<span class="symbol-marker">&fnof;</span>
{{/if}}
<a class="symbol-name" name="{{urlHash}}" href="#{{urlHash}}">{{displayName}}</a>{{paramStr}}
</h5>

<div class="documentation">{{{markdown documentation}}}</div>

{{#isFunction}}
<div class="parameter-heading mdl-typography--subhead">Parameters:</div>
<ul>
{{#parameters}}
<li class="parameter">
<span class="param-name">
{{name}}: {{{markdownInner type}}}
</span>
<span class="param-docs">
{{#optional}}(Optional){{/optional}} {{{markdownInner documentation}}}
</span>
</li>
{{/parameters}}
</ul>
<div class="returns mdl-typography--subhead">
Returns: <span class="return-type">{{{markdownInner returnType}}}</span>

<!-- Params -->
{{> paramList }}

<div class="returns">
<span class="returns-header">
Returns:
</span>
<span class="return-type">{{{markdownInner returnType}}}</span>
</div>
{{/isFunction}} {{#isClass}}
<h6>Methods:</h6>
Expand All @@ -345,19 +431,8 @@ <h6>Methods:</h6>
<span class="method-docs">
{{#optional}}(Optional){{/optional}} {{{markdownInner documentation}}}

<div class="parameter-heading mdl-typography--subhead">Parameters:</div>
<ul>
{{#parameters}}
<li class="parameter">
<span class="param-name">
{{name}}: {{{markdownInner type}}}
</span>
<span class="param-docs">
{{#optional}}(Optional){{/optional}} {{{markdownInner documentation}}}
</span>
</li>
{{/parameters}}
</ul>
<!-- Params -->
{{> paramList }}
</span>
</div>
{{/methods}} {{/isClass}}
Expand Down
8 changes: 4 additions & 4 deletions website/scripts/api-parser.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -50,13 +50,13 @@ export function parse():
subheadings: [
{
name: 'Creation',
description: `Tensors are the core datastructure of deeplearn.js.
description: `<p>Tensors are the core datastructure of deeplearn.js.
They are a generalization of vectors and matrices to potentially
higher dimensions.
<br><br>
We have utility functions for common cases like 1D, 2D, 3D
</p>
<p>We have utility functions for common cases like 1D, 2D, 3D
and 4D tensors, as well a number of functions to iniatialize
tensors in ways useful for machine learning`,
tensors in ways useful for machine learning</p>`,
pin: [
'tensor', 'scalar', 'tensor1d', 'tensor2d', 'tensor3d', 'tensor4d'
]
Expand Down

0 comments on commit 97bc9dd

Please sign in to comment.