sharpetronics/dream
1
0
Fork 0
mirror of https://github.com/aantron/dream.git synced 2025-12-16 00:05:08 -05:00
Code Issues Projects Releases Wiki Activity

Docs work

Browse Source
This commit is contained in:
Anton Bachin 2021-04-04 01:55:05 +03:00
parent bc0ed01a23
commit 6e91abcc12
6 changed files with 491 additions and 178 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

514
docs/web/site/docs.css
View File

@ -5,15 +5,11 @@
@import url('https://fonts.googleapis.com/css2?family=Tenor+Sans&display=swap');
/* Fonts. */ /* Fonts. */
/* @font-face { /* TODO Host Tenor Sans */
font-family: 'Lato';
font-style: normal;
font-weight: 100;
src: local(''),
url('lato-v17-latin-100.woff2') format('woff2');
} */
@font-face { @font-face {
font-family: 'Lato'; font-family: 'Lato';
@ -41,7 +37,7 @@
@font-face { @font-face {
font-family: 'Iosevka'; font-family: 'Iosevka';
font-style: norma; font-style: normal;
font-weight: 400; font-weight: 400;
src: local(''), src: local(''),
url('iosevka-regular.woff2') format('woff2'); url('iosevka-regular.woff2') format('woff2');
@ -54,6 +50,13 @@
src: url('fa-solid-900.woff2') format('woff2'); src: url('fa-solid-900.woff2') format('woff2');
} }
@font-face {
font-family: FontAwesomeBrands;
font-style: normal;
font-weight: 400;
src: url('fa-brands-400.woff2') format('woff2');
}
body { body {
font-family: Lato, -apple-system, BlinkMacSystemFont, Segoe UI, Roboto, Oxygen, Ubuntu, Cantarell, Open Sans, Helvetica Neue, Helvetica, Arial, sans-serif; font-family: Lato, -apple-system, BlinkMacSystemFont, Segoe UI, Roboto, Oxygen, Ubuntu, Cantarell, Open Sans, Helvetica Neue, Helvetica, Arial, sans-serif;
font-size: 16px; font-size: 16px;
@ -66,56 +69,120 @@ pre, code {
font-family: Iosevka, SFMono-Regular, Consolas, Liberation Mono, Menlo, monospace; font-family: Iosevka, SFMono-Regular, Consolas, Liberation Mono, Menlo, monospace;
} }
/* pre, code { header pre {
font-size: 13px; font-family: SFMono-Regular, Consolas, Liberation Mono, Menlo, monospace;
font-family: Fira Code, SFMono-Regular, Consolas, Liberation Mono, Menlo, monospace; }
} */
header code {
font-size: 16px;
}
h1 {
font-family: Tenor Sans, Lato, -apple-system, BlinkMacSystemFont, Segoe UI, Roboto, Oxygen, Ubuntu, Cantarell, Open Sans, Helvetica Neue, Helvetica, Arial, sans-serif;
}
h1 {
font-size: 96px;
line-height: 1;
position: relative;
left: -11px;
}
h6 {
font-size: 20px;
font-weight: normal;
}
.blurbs {
font-size: 18px;
line-height: 28px;
}
/* Colors and presentation styles. */ /* Colors and presentation styles. */
body { body {
background-color: #2a2a2a; background-color: #2c2c2c;
color: #eee; color: #eee;
} }
pre { .odoc-content pre {
background-color: #222; background-color: #111;
margin-left: 1em; margin-left: 1em;
margin-right: 1em; margin-right: 1em;
border: 1px solid black;
} }
.spec > pre { .odoc-content .spec > pre {
background: none; background: none;
margin: 0; margin: 0;
border: none;
} }
code { .odoc-content code {
color: #ddd; color: #ddd;
background-color: #111; background-color: #111;
padding: 0 3px; padding: 0 3px;
margin: 0 1px; margin: 0 1px;
white-space: nowrap; white-space: nowrap;
line-height: 20px;
} }
pre > code, .odoc-content pre > code,
.spec > code { .odoc-content .spec > code {
background: none; background: none;
padding: 0; padding: 0;
margin: 0; margin: 0;
color: inherit; color: inherit;
white-space: inherit; white-space: inherit;
line-height: inherit;
} }
/* p > code:first-child {
margin-left: -3px;
} */
h1, h2, h3 { h1, h2, h3 {
font-weight: 400; font-weight: 400;
color: white; color: white;
} }
header {
background-color: #32353d;
}
header .topmost {
background-color: #181818;
}
h1 {
text-shadow: -2px 2px black;
}
header pre {
padding: 27px 18px;
background-color: #1c1c1c;
line-height: 27px;
}
.blurbs {
color: white;
}
header pre, header pre code {
font-size: 18px;
}
header p {
margin-top: 12px;
margin-bottom: 12px;
}
header p .title {
font-family: Tenor Sans;
}
footer { footer {
opacity: 0.25; color: #666;
}
:target .backing {
background-color: #1c1c1c;
} }
nav ~ * a[href="#builtin"], nav ~ * a[href="#builtin"],
@ -137,16 +204,82 @@ a[href^=http]::after {
content: "\f35d"; content: "\f35d";
font-family: FontAwesome; font-family: FontAwesome;
font-size: 10px; font-size: 10px;
line-height: 18px;
color: #6e8ccf; color: #6e8ccf;
position: relative; position: relative;
top: -0.5px; top: -0.5px;
margin-left: 2px; margin-left: 2px;
margin-right: 3px; margin-right: 3px;
} }
a[href^=http] > code { .odoc-content a[href^=http] > code {
margin-right: -3px; margin-right: -3px;
} }
a, a:visited, a:active {
color: #a9c4ff;
text-decoration: none;
}
a:hover {
text-decoration: underline;
}
.odoc-content a > code {
color: #b8caea;
}
.hljs-module-access, .hljs-keyword, .keyword {
color: #ffef33;
}
.hljs-identifier, .hljs-literal, .hljs-type {
color: #92BFBF;
}
.hljs-string {
color: #BDDCDC;
}
.of {
color: #bec5cd;
}
.topmost ul {
list-style: none;
}
.topmost ul li {
height: 24px;
}
.topmost ul li::before
{
display: inline-block;
width: 2rem;
padding-right: 0.25rem;
text-align: center;
font-family: FontAwesome, FontAwesomeBrands;
font-size: 15px;
}
.topmost ul li:nth-child(3)::before {
content: '\f09b';
}
.topmost ul li:nth-child(1)::before {
content: '\f126';
}
.topmost ul li:nth-child(2)::before {
content: '\f49e';
font-size: 13px;
}
.topmost ul li:nth-child(4)::before {
content: '\f303';
font-size: 14px;
}
/* Geometry. /* Geometry.
@ -158,8 +291,12 @@ body {
position: relative; position: relative;
} }
body, p, h1, h2, h3 { .odoc-spec {
margin: 0em; max-width: 45rem;
}
body, p, h1, h2, h3, h6 {
margin: 0;
} }
footer { footer {
@ -175,6 +312,40 @@ p + p, p + pre, pre + p {
z-index: -2; z-index: -2;
} }
header {
overflow: auto;
padding-bottom: 36px;
}
header h1, header h6 {
/* text-align: center; */
}
header .topmost {
padding-top: 12px;
padding-bottom: 24px;
}
h2 {
padding-top: 96px;
margin-bottom: 48px;
}
h3 {
padding-top: 48px;
margin-bottom: 24px;
}
p + .odoc-spec {
margin-top: 36px;
}
.spec-doc {
margin-top: 12px;
margin-bottom: 36px;
margin-left: 1rem;
}
.spec-doc li + li { .spec-doc li + li {
margin-top: 12px; margin-top: 12px;
} }
@ -207,6 +378,10 @@ ul ul li {
/* Two-column geometry. */ /* Two-column geometry. */
@media (min-width: 1240px) { @media (min-width: 1240px) {
.odoc-spec {
max-width: none;
}
.spec { .spec {
float: left; float: left;
width: 28rem; width: 28rem;
@ -215,11 +390,12 @@ ul ul li {
.background { .background {
position: absolute; position: absolute;
top: 96px; top: 0;
left: 0; left: 0;
height: calc(100% - 96px); height: 100%;
width: 43rem; width: 43rem;
background-color: #262626; background-color: #262626;
border-right: 1px solid #2222;
} }
h2, h2 ~ :not(.odoc-spec):not(nav), footer { h2, h2 ~ :not(.odoc-spec):not(nav), footer {
@ -227,6 +403,10 @@ ul ul li {
max-width: 30rem; max-width: 30rem;
clear: both; clear: both;
} }
.odoc-content > pre {
margin-left: 31rem !important;
max-width: 28rem !important;
}
.spec.multiline { .spec.multiline {
margin-bottom: 36px; margin-bottom: 36px;
@ -235,7 +415,14 @@ ul ul li {
.spec-doc { .spec-doc {
float: left; float: left;
width: 30rem; width: 30rem;
margin-top: 0;
margin-bottom: 18px; margin-bottom: 18px;
margin-left: 0;
}
header .blurbs {
float: left;
width: 30rem;
} }
.spec-doc > p ~ p:last-child, .spec-doc > p ~ pre:last-child { .spec-doc > p ~ p:last-child, .spec-doc > p ~ pre:last-child {
@ -275,46 +462,163 @@ ul ul li {
margin-top: -3.125em; margin-top: -3.125em;
margin-bottom: 72px; margin-bottom: 72px;
} }
header .topmost {
padding-left: 14rem;
overflow: auto;
}
.topmost .titles {
float: left;
width: 29.6em;
}
.topmost ul {
float: left;
max-width: 46em;
padding-left: 0;
}
header pre {
float: left;
width: 24rem;
margin-top: 48px;
margin-left: 14rem;
margin-right: 4rem;
}
header .blurbs {
float: left;
margin-top: 24px;
max-width: 46rem;
padding-left: 0;
padding-right: 0;
}
} }
@media (min-width: 1400px) { @media (min-width: 1400px) {
.spec-doc { .spec-doc {
width: 40rem; width: 40rem;
} }
h2, h2 ~ :not(.odoc-spec):not(nav) {
header .blurbs {
width: 40rem;
}
h2, h2 ~ :not(.odoc-spec):not(nav), footer {
max-width: 40rem; max-width: 40rem;
} }
.odoc-content > pre {
max-width: 38rem !important;
}
} }
@media (min-width: 1520px) { @media (min-width: 1520px) {
.spec-doc { .spec-doc {
width: 46rem; width: 46rem;
} }
h2, h2 ~ :not(.odoc-spec):not(nav) {
header .blurbs {
width: 46rem;
}
h2, h2 ~ :not(.odoc-spec):not(nav), footer {
max-width: 46rem; max-width: 46rem;
} }
.odoc-content > pre {
max-width: 44rem !important;
}
} }
/* Floating TOC. */ /* Floating TOC. */
body > *:not(header), .topmost, .blurbs {
padding-left: 1em;
padding-right: 1em;
}
.odoc-toc ul {
columns: 2;
list-style: none;
}
h2:first-of-type {
padding-top: 48px;
}
@media (min-width: 550px) {
.odoc-toc ul {
columns: 3;
}
}
@media (min-width: 800px) { @media (min-width: 800px) {
body > * {
padding-left: 0;
padding-right: 0;
/* padding-left: 14rem; */
}
.odoc-content, body > footer {
padding-left: 14rem;
}
.odoc-toc { .odoc-toc {
position: fixed; position: absolute;
top: 0; /* top: 580px; */
left: 0; left: 0;
height: 100%; height: 100%;
width: 12rem; width: 12rem;
overflow-y: scroll;
scrollbar-width: none;
line-height: 30px; line-height: 30px;
border-right: 1px solid #111; border-right: 1px solid #1e1e1e;
background-color: #222; background-color: #222;
color: #ddd;
}
.odoc-toc::-webkit-scrollbar {
display: none;
}
.odoc-toc.fixed {
position: fixed;
top: 0;
} }
body { .odoc-toc ul {
padding-left: 14rem; columns: 1;
padding: 0;
margin-top: 30px;
margin-bottom: 30px;
}
.odoc-toc li {
padding-left: 2em;
}
.odoc-toc a,
.odoc-toc a:visited,
.odoc-toc a:active {
color: inherit;
display: inline-block;
width: 100%;
}
.odoc-toc.fixed .current-section {
background-color: #92a4cc;
color: black;
font-weight: bold;
/* background-color: black;
font-weight: bold; */
}
h2:first-of-type {
padding-top: 36px;
} }
} }
pre { .odoc-content pre {
padding: 12px; padding: 12px;
} }
.spec > pre { .odoc-content .spec > pre {
padding: 0; padding: 0;
} }
@ -362,10 +666,6 @@ h2 .anchor::before, h3 .anchor::before {
left: 0px; left: 0px;
} }
:target .backing {
background-color: #1c1c1c;
}
.backing { .backing {
position: absolute; position: absolute;
left: 0; left: 0;
@ -384,135 +684,3 @@ h3 .backing {
.spec .backing { .spec .backing {
height: 1.5em; height: 1.5em;
} }
/* Uncateogorized. */
a > code {
color: #b8caea;
}
/* p, pre {
margin-top: 12px;
margin-bottom: 12px;
}
.spec > pre {
margin-top: 24px;
} */
/* .spec > pre.compact {
margin-bottom: 0;
}
p + p {
margin-top: 24px;
} */
/* .odoc-content > ol > li {
margin-top: 60px;
margin-bottom: 72px;
} */
/* body.index h1 {
text-align: center;
font-family: Lato, sans-serif;
font-size: 800%;
font-weight: 100;
text-transform: uppercase;
line-height: 1;
}
h1 {
margin-top: 48px;
margin-bottom: 24px;
font-weight: 400;
font-size: 32px;
}
h2 {
margin-top: 96px;
margin-bottom: 24px;
font-weight: 400;
clear: both;
}
h3 {
margin-top: 36px;
margin-bottom: 24px;
font-weight: 400;
clear: both;
} */
a, a:visited, a:active {
color: #a9c4ff;
text-decoration: none;
}
a:hover {
text-decoration: underline;
}
nav.odoc-toc ul {
list-style: none;
padding: 0;
margin-top: 30px;
margin-bottom: 30px;
}
nav.odoc-toc a,
nav.odoc-toc a:visited,
nav.odoc-toc a:active {
color: inherit;
display: inline-block;
width: 100%;
}
nav.odoc-toc li {
padding-left: 2em;
}
nav.odoc-toc .current-section {
background-color: #111;
}
.hljs-module-access, .hljs-keyword, .keyword {
color: #ffef33;
}
.hljs-identifier, .hljs-literal, .hljs-type {
color: #92BFBF;
}
.hljs-string {
color: #BDDCDC;
}
.of {
color: #bec5cd;
}
/* .spec-doc > :first-child {
margin-top: 0;
}
.spec-doc {
padding-left: 2.25em;
margin-top: 6px;
margin-bottom: 48px;
} */
/* p + .odoc-spec {
margin-top: 48px;
} */
/* ol {
padding-left: 18px; */
/* }
.spec {
color: white;
} */

17
docs/web/site/docs.js
View File

@ -26,4 +26,19 @@ function current_section() {
} }
}; };
window.onscroll = current_section; function sidebar_position() {
var toc = document.querySelector(".odoc-toc");
var header = document.querySelector("header");
if (window.scrollY >= header.offsetHeight)
toc.classList.add("fixed");
else {
toc.classList.remove("fixed");
}
};
function scroll() {
current_section();
sidebar_position();
};
window.onscroll = scroll;

BIN
docs/web/site/fa-brands-400.woff2 Normal file
View File

Binary file not shown.

130
docs/web/templates/index.html
View File

@ -17,13 +17,141 @@
<body class="index"> <body class="index">
<header> <header>
<div class="topmost">
<div class="titles">
<h1>Dream</h1> <h1>Dream</h1>
<h6>Tidy Web framework for OCaml and ReasonML</h6>
</div>
<ul>
<li><code>1.0.0~alpha1</code></li>
<li><code>opam install dream</code></li>
<li><a href="https://github.com/aantron/dream">GitHub</a></li>
<li><a href="https://github.com/aantron/dream/blob/master/src/dream.mli">Edit these docs</a></li>
</ul>
</div>
<pre><span class="keyword">let</span> greet who =
<span class="hljs-type">&lt;html></span>
<span class="hljs-type">&lt;body></span>
<span class="hljs-type">&lt;h1></span><span class="hljs-string">Hello, </span>&lt;%s who %><span class="hljs-string">!</span><span class="hljs-type">&lt;/h1></span>
<span class="hljs-type">&lt;/body></span>
<span class="hljs-type">&lt;/html></span>
<span class="keyword">let</span> <span class="hljs-string">()</span> =
<span class="hljs-type">Dream</span>.run
<span class="hljs-string">@@</span> <span class="hljs-type">Dream</span>.logger
<span class="hljs-string">@@</span> <span class="hljs-type">Dream</span>.router <span class="hljs-string">[</span>
<span class="hljs-type">Dream</span>.get <span class="hljs-string">"/"</span> <span class="hljs-string">@@</span> <span class="keyword">fun</span> _ ->
<span class="hljs-type">Dream</span>.respond (greet <span class="hljs-string">"world"</span>);
<span class="hljs-string">]</span>
<span class="hljs-string">@@</span> <span class="hljs-type">Dream</span>.not_found</pre>
<!-- Send TLS link to HTTPS example. -->
<div class="blurbs">
<p>
<span class="title"><strong>Dream</strong></span> is an easy-to-use Web
framework, whose entire <a href="#types">interface</a> fits on this page!
</p>
<p>
It supports <a href="#servers">TLS</a>,
<a href="#websockets">WebSockets</a>, and <a href="#graphql">GraphQL</a>.
HTTP/2 support is <a href="#servers">transparent</a>. It also includes:
<ul>
<li>
a nice <a href="#logging">log</a> and default OCaml runtime
configuration;
</li>
<li>
easy-to-use, secure helpers for round-tripping
<a href="#cookies">cookies</a> and <a href="#forms">forms</a>;
</li>
<li>
<a href="#templates">templates</a> that interleave OCaml with the
already-familiar HTML;
</li>
<li>
a fully composable <a href="#routing">router</a>;
</li>
<li>
<a href="#sessions">session management</a> with pluggable
<a href="#back-ends">back ends</a>; and
</li>
<li>
unified <a href="#errors">error handling</a> that leaks no English
strings from any level of your app.
</li>
</ul>
<p>
You can integrate Dream into a fully self-contained binary, or run it in
large deployments behind proxies. Dream assumes no databases, environment
variables, or configuration files, and requires no setup beyond installing
the one package, <code>dream</code>.
</p>
<p>
Dream sticks to base OCaml types as much as possible, introducing only a
few <a href="#types">types</a> of its own. Dream handlers and middlewares
are just bare functions. Dream has a flat namespace and aims for maximal
clarity.
</p>
<p>
This page is the API documentation, but Dream also has:
</p>
<ul>
<li>
A <a href="https://github.com/aantron/dream/tree/master/example#readme">
Tutorial</a> &mdash; get started at
<a href="https://github.com/aantron/dream/tree/master/example/1-hello#files">
<code>1-hello</code></a>!
</li>
<li>
Many <a href="https://github.com/aantron/dream/tree/master/example#reason">
Examples</a>, covering all kinds of scenarios.
</li>
</ul>
</div>
</header> </header>
<!-- TODO Real getting started instructions link. -->
<!-- <header>
<p>
<span class="title">Dream</span> is a web framework ...
HTTP2, TLS, runs without a proxy, integration, scaling, GraphQL, etc.
</p>
<pre><code>let greet who =
&lt;html>&lt;body>&lt;h1>Hello, &lt;%s who %>!&lt;/h1>&lt;/body>&lt;/html>
let () =
Dream.run
@@ Dream.logger
@@ Dream.router [
Dream.get "/" @@ fun _request -> Dream.respond (greet "world");
]
@@ Dream.not_found
</code></pre>
</header> -->
<!-- Replaced by Soupault with postprocessed odoc output. --> <!-- Replaced by Soupault with postprocessed odoc output. -->
<div id="api"></div> <div id="api"></div>
<footer>Copyright © 2021 Anton Bachin. Released under the MIT license.</footer> <footer>
Copyright © 2021 Anton Bachin.
<br>
Released under the MIT license. See
<a href="https://github.com/aantron/dream/blob/master/LICENSE.md">
LICENSE.md
</a>
</footer>
</body> </body>
</html> </html>

4
src/dream.mli
View File

@ -75,7 +75,7 @@ and route
The three handler-related types have a vaguely algebraic interpretation: The three handler-related types have a vaguely algebraic interpretation:
- Literal {!type-handler}s are atoms. - Literal handlers are atoms.
- {!type-middleware} is for sequential composition (product-like). - {!type-middleware} is for sequential composition (product-like).
- {!type-route} is for alternative composition (sum-like). - {!type-route} is for alternative composition (sum-like).
@ -2088,7 +2088,7 @@ val sort_headers : (string * string) list -> (string * string) list
header order. This function can help sanitize output before comparison. *) header order. This function can help sanitize output before comparison. *)
val echo : handler val echo : handler
(** Respomds with the request body. *) (** Responds with the request body. *)

2
src/middleware/session.ml
View File

@ -190,6 +190,8 @@ end
(* TODO This probably needs format prefixes. *) (* TODO This probably needs format prefixes. *)
(* TODO JSON is probably not a good choice for the contents. However, there (* TODO JSON is probably not a good choice for the contents. However, there
doesn't seem to be a good alternative in opam right now, so using JSON. *) doesn't seem to be a good alternative in opam right now, so using JSON. *)
(* TODO Should still generate and send keys, for potential revocation
implementations. *)
module Cookie = module Cookie =
struct struct
let create expires_at = { let create expires_at = {