From a52a8d70e98d35e730b4f6a36f0579ca686b0489 Mon Sep 17 00:00:00 2001 From: Jonah Scheinerman Date: Sun, 7 Jul 2019 03:15:58 -0400 Subject: [PATCH] Improve docs (#124) --- docs/builtin.md | 2 +- docs/images/github-icon.png | Bin 0 -> 1571 bytes docs/index.md | 2 ++ docs/limitations.md | 2 +- docsgen/index.tsx | 18 ++++++++++++++++-- docsgen/markdown.tsx | 14 ++++++++++---- docsgen/page.tsx | 6 +++--- docsgen/sidebar.tsx | 14 +++++++++++--- docsgen/style.ts | 5 +++-- 9 files changed, 47 insertions(+), 16 deletions(-) create mode 100644 docs/images/github-icon.png diff --git a/docs/builtin.md b/docs/builtin.md index efc73d8..e87322c 100644 --- a/docs/builtin.md +++ b/docs/builtin.md @@ -2,7 +2,7 @@ While users can define their own unit system (see [Defining Quantities](defining-quantities.html)), Safe Units also comes with a large collection of built-in quantities and units based on the SI unit system. -All quantities provided are generic, of the form `type Quantity` so all will default to using `number` as the numeric type but may be passed another numeric type. +All quantities provided are generic, of the form `type Quantity` so all quantity types will default to using `number` as the numeric type but may be passed another numeric type. ## Base Units diff --git a/docs/images/github-icon.png b/docs/images/github-icon.png new file mode 100644 index 0000000000000000000000000000000000000000..628da97c70890c73e59204f5b140c4e67671e92d GIT binary patch literal 1571 zcmaJ>c~BE~6izDPQq)#Nu*KOf(n^(VHY9;fiINM65``pc+9*v(mL$bwfCjbc%v9V{8r9iX|O%>Nr%pLD2qT{mty}c=LVleeamv znz3SOSm@kP8jThvOOq(56Yzh*fz(booe!uZij=BJC6+_lbvQ~B8nA2>kXdv_RDtRY z`5QXWWEySCe6vbTs^#f?J!WC*{1~RgVx!nJTJjQyO{dRANgx|FnymtGbD9%JmCh9^y)##j7{Dcqfn*1ta$rG89pJF6w-S7Z037$rr|y0;1Onp_ zGFJdT6Q!1C0AdVB0WOmpuV=AgAQ550Tn+-mivTtYPJmz*#75#_n9oV%!#rSOfmAfy zki%C~=fTp1{O#BLpJ|0jj#m6#|LRWit-vq3PE1z9ZqyvET4sX$-Icqy7t z<=aq5ff86AuBZBu6EjJsYWM0uejufWFTwPA7Su}0Bm$7KFb!q{Um_8~A{LUG#1l(l zSehUda@kU8LIRg9fkk2tZ;~ss5~R+mM<==F7hLHpxqLB>>PQS%Vc7b~?q!%T5+h8Q z4G=4Nzyi5WZ?^gkasJ{?Xhm`JC#WG6$1K2jb@=9&D3EgD#3UhGh#*21rJjulVXjCF zvp76q62jt0zzMG5C7DlfMgPl%C^3+~wf|}Lq=}jz|MmIcQjh1Ok6NjD$Em^Iv26D> z8tt_TnM9~^Tt8mflRGPOrrX|HtT3gG4LEuuk{g2Rn}QgJIa?gZo))!!=o_l9bvD%A zZ`aHajl8#~u?!4f7F#*b*->A=R2L)6!>saz?h>#wTXT-I(XmQ zx{84skS>k=i~i`(6k4C7;Zpfx%dCPVjPayMf8pugtGM=~s=Id1l#8MZJ1-73wV#Q3 zR3>v3%}jbQs1f_Z0xo;%=LILlA+nTpKI4ha%xWW}uqHrNao~&T4AY6m`P$_n-6h*g zhoX+e4n%~gl_lhe#s+AMb7d{5WzvYTa%6Q~si@@4{;s(0zU|H&P3fE+t{7X`S#Cj@ zC#vd}^4pcBD*77Ny5=j$h8EL2_t$O38$SQiJ6fPjJMimypr~MB2(&P0aI|h}$64<0 z>_~duqNjaT=DM^6+N{&B_lED;F2wrl?!4Lk*2((x!fmrcsw+=cI^qttuZ9C}-m~5E z-ryYVpL%^xR#&(0YI5hz<(}F7-p)?FPcyJO-zVO>%9ZDXJH8pnY;GJYFDQ>vd#j_* zRrd}L(r=!g+1#nQwsO?kpS`Qq8`NxE+Zy{gf7*_7J*U2V_|NpLo{iasj7VCg_V9&| ShohtYzipXxh2)4xTk6 in this library (though, why would you?). +Since Safe Units is typesafe, it must compute units at compile time. Due to some technical limitations of what you can do with types in TypeScript, there is one major limitation to this library: The exponents for dimensions of your units are limited to integers between -5 and 5, inclusive. (However, under the hood these are represented by string literals between `"-5"` and `"5"`). This means that you can not represent a value of 30 m⁶ in this library (though, why would you?). In the research I've conducted for this library I cannot find any instances in which it would be useful to use units with such extreme exponents. If you're aware of any such use cases, please [file an issue](https://github.com/jscheiny/safe-units/issues/new) to discuss it. diff --git a/docsgen/index.tsx b/docsgen/index.tsx index ff0471d..c4a9323 100644 --- a/docsgen/index.tsx +++ b/docsgen/index.tsx @@ -20,7 +20,8 @@ const renderPageHtml = (title: string, body: string, inlineStyles: string, linke ${body} `; -const buildDir = join("docs", "build"); +const docsDir = "docs"; +const buildDir = join(docsDir, "build"); if (!existsSync(buildDir)) { mkdirSync(buildDir); } @@ -30,6 +31,13 @@ if (!existsSync(stylesDir)) { mkdirSync(stylesDir); } +const imagesContextPath = "images"; +const imagesInDir = join(docsDir, imagesContextPath); +const imagesOutDir = join(buildDir, imagesContextPath); +if (!existsSync(imagesOutDir)) { + mkdirSync(imagesOutDir); +} + const pages = readdirSync("docs") .filter(path => extname(path) === ".md") .map(path => join("docs", path)) @@ -73,10 +81,16 @@ function buildLinkedStyles(inPath: string): string { return ``; } -const linkedStyles = ["node_modules/highlight.js/styles/monokai.css", "node_modules/normalize.css/normalize.css"] +const linkedStyles = ["node_modules/highlight.js/styles/dracula.css", "node_modules/normalize.css/normalize.css"] .map(buildLinkedStyles) .join("\n"); +readdirSync(imagesInDir).forEach(path => { + const inPath = join(imagesInDir, path); + const outPath = join(imagesOutDir, path); + copyFileSync(inPath, outPath); +}); + pages.sort(orderBy(order)); pages.forEach((page, index) => { const body = ReactDOMServer.renderToString(); diff --git a/docsgen/markdown.tsx b/docsgen/markdown.tsx index aace4f3..23f9324 100644 --- a/docsgen/markdown.tsx +++ b/docsgen/markdown.tsx @@ -139,18 +139,24 @@ function getHeadingTag(level: number): keyof JSX.IntrinsicElements { const CodeBlock = component("code-block", "code", { borderRadius: 3, + $nest: { + "&&": { + padding: 20, + }, + }, }); -const CodeInline = component("code-line", "code", { - color: "#00998C", +const CodeInline = component("code-inline", "code", { + color: "#6272a4", + fontSize: 18, }); export const Link = component("link", "a", { - color: "#BF8C0A", + color: "#008075", textDecoration: "none", $nest: { "&:hover": { - color: "#A67908", + color: "#00B3A4", textDecoration: "underline", }, }, diff --git a/docsgen/page.tsx b/docsgen/page.tsx index bdac87a..d245e12 100644 --- a/docsgen/page.tsx +++ b/docsgen/page.tsx @@ -49,16 +49,17 @@ const Contents = component("contents", "div", { flex: "1 1 auto", position: "relative", background: "#EBF1F5", - boxShadow: "inset 15px 0 20px -20px #182026", + boxShadow: "inset 15px 0 30px -30px #182026", }); const Body = component("body", "div", { maxWidth: 800, - margin: "0 25px 25px 45px", + margin: "0 25px 25px 55px", }); const EndMatter = component("end-matter", "div", { borderTop: "1px solid #BFCCD6", + textAlign: "center", marginTop: 20, paddingTop: 20, fontSize: 14, @@ -66,7 +67,6 @@ const EndMatter = component("end-matter", "div", { const License = component("license", "div", { marginTop: 20, - textAlign: "center", color: "#738694", textShadow: "0 1px 0 white", fontSize: 12, diff --git a/docsgen/sidebar.tsx b/docsgen/sidebar.tsx index 6821d05..416c900 100644 --- a/docsgen/sidebar.tsx +++ b/docsgen/sidebar.tsx @@ -36,14 +36,14 @@ export const Sidebar: React.FunctionComponent = ({ pages, selecte return ( {links} - - View on github + + View on github ); }; -const HOME_COLOR = "#008075"; +const HOME_COLOR = "#6272a4"; const LINK_COLOR = "#293742"; const Container = component("sidebar", "div", { @@ -64,6 +64,8 @@ const PageLink = component("page-link", "a", { padding: "5px 10px", background: "#E1E8ED", fontWeight: "bold", + display: "flex", + alignItems: "center", $nest: { "&:hover": { background: "#BFCCD6", @@ -121,3 +123,9 @@ const LinkSection = component("links", "div", { }, }, }); + +const GithubIcon = component("links", "img", { + width: 14, + height: 14, + marginRight: 5, +}); diff --git a/docsgen/style.ts b/docsgen/style.ts index 357b3f0..7a9aaba 100644 --- a/docsgen/style.ts +++ b/docsgen/style.ts @@ -23,8 +23,9 @@ export function component( } cssRule("body", { - fontFamily: "'Helvetica Neue', HelveticaNeue, Helvetica, Arial, sans-serif", + fontFamily: `"Open Sans", "Helvetica Neue", Helvetica, Arial, sans-serif`, fontSize: 16, + lineHeight: 1.5, }); cssRule("body pre, body code", { @@ -40,7 +41,7 @@ cssRule("h2, h3", { }); cssRule("body h1", { - color: "#008075", + color: "#6272a4", margin: 0, paddingBottom: 20, paddingTop: 25,