Improve docs (#124)

jscheiny · Jul 7, 2019 · a52a8d7 · a52a8d7
1 parent 8ba2175
commit a52a8d7
Show file tree

Hide file tree

Showing 9 changed files with 47 additions and 16 deletions.
diff --git 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<N = number>` 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<N = number>` 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
diff --git a/docs/index.md b/docs/index.md
@@ -1,5 +1,7 @@
 # Safe Units
 
+[![Build Status](https://travis-ci.org/jscheiny/safe-units.svg?branch=master)](https://travis-ci.org/jscheiny/safe-units) [![NPM Version](https://img.shields.io/npm/v/safe-units.svg)](https://www.npmjs.com/package/safe-units) [![MIT License](https://img.shields.io/npm/l/safe-units.svg)](https://github.com/jscheiny/safe-units/blob/master/LICENSE)
+
 Safe Units is a library for using units of measurement in TypeScript in a type safe manner. Check it out on [github](https://github.com/jscheiny/safe-units). Safe Units provides an implementation of an SI based unit system but is flexible enough to allow users to create their own unit systems which can be independent or can interoperate with the built-in units. Users can also make unit systems for any numeric type they'd like not just the JavaScript `number` type. This library makes heavy use of conditional types and thus requires TypeScript 2.9 or higher.
 
 ```ts

diff --git a/docs/limitations.md b/docs/limitations.md
@@ -1,6 +1,6 @@
 # Limitations
 
-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<sup>6</sup> 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
@@ -20,7 +20,8 @@ const renderPageHtml = (title: string, body: string, inlineStyles: string, linke
     <body>${body}</body>
 </html>`;
 
-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 `<link rel="stylesheet" type="text/css" media="screen" href="styles/${name}" />`;
 }
 
-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(<Page pages={pages} pageIndex={index} />);

diff --git 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
@@ -49,24 +49,24 @@ 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,
 });
 
 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
@@ -36,14 +36,14 @@ export const Sidebar: React.FunctionComponent<ISidebarProps> = ({ pages, selecte
     return (
         <Container>
             {links}
-            <PageLink className={homeLink} href="https://github.com/jscheiny/safe-units">
-                View on github
+            <PageLink className={selectedPage} href="https://github.com/jscheiny/safe-units">
+                <GithubIcon src="images/github-icon.png" /> View on github
             </PageLink>
         </Container>
     );
 };
 
-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
@@ -23,8 +23,9 @@ export function component<Tag extends keyof JSX.IntrinsicElements>(
 }
 
 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,