New SDK Reference Website

package.json

@@ -28,6 +28,7 @@
     "express": "^4.16.2",
     "fs-extra": "^4.0.2",
     "jsdoc": "^3.6.3",
+    "jsdoc-to-markdown": "^6.0.1",
     "jshint": "^2.9.6",
     "karma": "^4.0.0",
     "karma-chai": "^0.1.0",
@@ -39,7 +40,7 @@
     "karma-sinon": "^1.0.5",
     "karma-sourcemap-loader": "^0.3.7",
     "mocha": "^4.0.1",
-    "prettier": "^1.16.4",
+    "prettier": "^2.1.1",
     "requirejs": "^2.3.6",
     "rollup": "^1.4.1",
     "rollup-plugin-babel": "^4.3.2",
@@ -53,7 +54,14 @@
     "uglify-js": "^2.0.0"
   },
   "scripts": {
+    "postinstall": "cd website/ && yarn install",
     "test": "make test",
-    "dev": "node test/browser/server.js"
+    "dev": "node test/browser/server.js",
+    "docs:generate-jsdoc": "node website/generate-jsdoc",
+    "docs:start": "cd website/ && yarn start",
+    "docs:build": "cd website/ && yarn build",
+    "docs:serve": "cd website/ && yarn serve",
+    "docs:deploy": "cd website/ && yarn deploy",
+    "docs:swizzle": "cd website/ && yarn swizzle"
   }
 }

website/.gitignore

@@ -0,0 +1,26 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Generated jsdoc markdown
+docs/Amplitude.md
+docs/AmplitudeClient.md
+docs/Identify.md
+docs/Revenue.md
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

website/README.md

@@ -0,0 +1,33 @@
+# Website
+
+The JavaScript SDK API Reference website is built using [Docusaurus 2](https://v2.docusaurus.io/), a modern static website generator.
+
+### Installation
+
+Installation is automatically done when `yarn install` is ran from the base directory.
+
+### Generating `website/docs/` from `src/`
+
+The website autogenerates markdown files of public classes and its contents using [generate-jsdoc.js](https://github.com/amplitude/Amplitude-JavaScript/blob/master/website/generate-jsdoc.js). 
+
+This is done by calling `yarn docs:generate-jsdoc` from the base directory.
+
+### Local Development Build
+
+Run `yarn start` from this directory or `yarn docs:start` from the base directory.
+
+Because of a bug with how Docusaurus handles `baseUrl` in `docusaurus.config.js`, you should open `localhost:3000/Amplitude-JavaScript` instead of the default `localhost:3000/`
+
+### Local Production Build
+
+Similar to local development build process. This command generates static content into the `website/build/` directory and creates a server to serve it.
+
+Run `yarn serve` from this directory or `yarn docs:serve` from the base directory. Then open `localhost:3000/Amplitude-JavaScript`
+
+### Deployment
+
+```
+$ GIT_USER=<Your GitHub username> USE_SSH=true yarn deploy
+```
+
+This will create the production build and push it the `gh-pages` branch.

website/babel.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};

website/docusaurus.config.js

@@ -0,0 +1,55 @@
+module.exports = {
+  title: 'Amplitude JS SDK Docs',
+  tagline: 'Amplitude JavaScript SDK',
+  url: 'https://amplitude.github.io',
+  baseUrl: '/Amplitude-JavaScript/',
+  onBrokenLinks: 'throw',
+  favicon: 'img/amp_favicon.ico',
+  organizationName: 'Amplitude',
+  projectName: 'Amplitude-JavaScript',
+  themeConfig: {
+    sidebarCollapsible: false,
+    navbar: {
+      logo: {
+        alt: 'Amplitude Logo',
+        src: 'img/amp_logo.svg',
+      },
+      hideOnScroll: true,
+      items: [
+        {
+          href: 'https://github.com/amplitude/Amplitude-JavaScript/',
+          label: 'GitHub',
+          position: 'left',
+        },
+      ],
+    },
+    footer: {
+      logo: {
+        alt: 'Amplitude Logo',
+        src: 'img/amp_logo.svg',
+      },
+      copyright: `Copyright © ${new Date().getFullYear()} Amplitude, Inc.`,
+    },
+    prism: {
+      defaultLanguage: 'javascript',
+    },
+  },
+  presets: [
+    [
+      '@docusaurus/preset-classic',
+      {
+        docs: {
+          homePageId: 'AmplitudeClient',
+          path: 'docs',
+          routeBasePath: '/',
+          sidebarPath: require.resolve('./sidebars.js'),
+          editUrl:
+            'https://github.com/amplitude/Amplitude-JavaScript/website',
+        },
+        theme: {
+          customCss: require.resolve('./src/css/custom.css'),
+        },
+      },
+    ],
+  ],
+};

website/generate-jsdoc.js

@@ -0,0 +1,77 @@
+const jsdoc2md = require("jsdoc-to-markdown");
+const fs = require("fs");
+const path = require("path");
+const prettier = require("prettier");
+const publicFiles = [
+  "amplitude-client.js",
+  "amplitude.js",
+  "identify.js",
+  "revenue.js",
+];
+const srcDir = path.join(__dirname, "../", "src");
+const outputDir = path.join(__dirname, "docs");
+function generateMarkdown(inputFile) {
+  const inputFilePath = path.join(srcDir, inputFile);
+  const data = jsdoc2md.getTemplateDataSync({ files: inputFilePath });
+  const className = data.find((e) => e.kind === "class").name;
+  const filteredData = data.filter(
+    (e) =>
+      e.kind === "constructor" ||
+      (e.access === "public" && (e.kind === "function" || e.kind === "member"))
+  );
+  const outputFilePath = path.join(outputDir, `${className}.md`);
+
+  const markdownOutput = filteredData
+    .map((item) => documentItem(item))
+    .join("\n");
+  fs.writeFileSync(
+    path.join(outputDir, `${className}.md`),
+    prettier.format(markdownOutput, { parser: "markdown" })
+  );
+}
+
+function documentItem(data) {
+  return `## \`${data.id}\`
+
+${data.examples ? documentExamples(data) : ""}
+
+${data.description || ""} 
+
+${data.params ? documentParams(data) : ""}
+
+${data.returns ? documentReturn(data) : ""}
+`;
+}
+
+function documentExamples(data) {
+  return `\`\`\`
+${data.examples}
+\`\`\`
+`;
+}
+
+function documentParams(data) {
+  const params = data.params.map(
+    (param) => `- \`${param.name}\` (\`${param.type.names[0]}\`)
+${param.description}
+`
+  );
+  return `### Parameters
+${params.join("\n")}
+`;
+}
+
+function documentReturn(data) {
+  return `### Return Value
+- (\`${data.returns[0].type.names[0]}\`)
+${data.returns[0].description}
+`;
+}
+
+if (!fs.existsSync(outputDir)) {
+  fs.mkdirSync(outputDir);
+}
+
+for (const file of publicFiles) {
+  generateMarkdown(file);
+}

website/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "docs",
+  "version": "0.0.0",
+  "private": true,
+  "scripts": {
+    "docusaurus": "docusaurus",
+    "start": "docusaurus start",
+    "build": "docusaurus build",
+    "swizzle": "docusaurus swizzle",
+    "deploy": "docusaurus deploy",
+    "serve": "docusaurus build --out-dir build/Amplitude-JavaScript && yarn run docusaurus serve"
+  },
+  "dependencies": {
+    "@docusaurus/core": "^2.0.0-alpha.61",
+    "@docusaurus/preset-classic": "^2.0.0-alpha.61",
+    "@mdx-js/react": "^1.5.8",
+    "clsx": "^1.1.1",
+    "react": "^16.8.4",
+    "react-dom": "^16.8.4"
+  },
+  "browserslist": {
+    "production": [
+      ">0.1%",
+      "not dead",
+      "not op_mini all"
+    ],
+    "development": [
+      "last 2 chrome version",
+      "last 2 firefox version",
+      "last 2 safari version"
+    ]
+  }
+}

website/sidebars.js

@@ -0,0 +1,5 @@
+module.exports = {
+  sidebar: {
+    'API Reference': ['AmplitudeClient', 'Amplitude', 'Identify', 'Revenue'],
+  },
+};

website/src/css/custom.css

@@ -0,0 +1,54 @@
+/* stylelint-disable docusaurus/copyright-header */
+/**
+ * Any CSS included here will be global. The classic template
+ * bundles Infima by default. Infima is a CSS framework designed to
+ * work well for content-centric websites.
+ */
+
+/* You can override the default Infima variables here. */
+:root {
+  --ifm-color-primary: #007fd2;
+  --ifm-color-primary-dark: #005488;
+  --ifm-color-primary-darker: #003b61;
+  --ifm-color-primary-darkest: #0c2a4b;
+  --ifm-color-primary-light: #48a4de;
+  --ifm-color-primary-lighter: #7bbee7;
+  --ifm-color-primary-lightest: #c6e2f4;
+  --ifm-code-font-size: 95%;
+}
+
+.docusaurus-highlight-code-line {
+  background-color: rgb(72, 77, 91);
+  display: block;
+  margin: 0 calc(-1 * var(--ifm-pre-padding));
+  padding: 0 var(--ifm-pre-padding);
+}
+
+/* OG site color #10069f */
+/* logo color #007fd2 */
+/* sidebar dark #003b61 */
+/* sidebar darkest #0c2a4b */
+/* Sidebar text ##c6d0d9 */
+
+/* $cerulean-50: #f4faff;
+$cerulean-100: #e4f1fa;
+$cerulean-200: #c6e2f4;
+$cerulean-300: #7bbee7;
+$cerulean-400: #48a4de;
+$cerulean-500: #007fd2;
+$cerulean-600: #0065a5;
+$cerulean-700: #005488;
+$cerulean-800: #003b61;
+$cerulean-900: #0c2a4b;
+:export {
+  cerulean-50: $cerulean-50;
+  cerulean-100: $cerulean-100;
+  cerulean-200: $cerulean-200;
+  cerulean-300: $cerulean-300;
+  cerulean-400: $cerulean-400;
+  cerulean-500: $cerulean-500;
+  cerulean-600: $cerulean-600;
+  cerulean-700: $cerulean-700;
+  cerulean-800: $cerulean-800;
+  cerulean-900: $cerulean-900;
+} */

website/src/pages/styles.module.css

@@ -0,0 +1,37 @@
+/* stylelint-disable docusaurus/copyright-header */
+
+/**
+ * CSS files with the .module.css suffix will be treated as CSS modules
+ * and scoped locally.
+ */
+
+.heroBanner {
+  padding: 4rem 0;
+  text-align: center;
+  position: relative;
+  overflow: hidden;
+}
+
+@media screen and (max-width: 966px) {
+  .heroBanner {
+    padding: 2rem;
+  }
+}
+
+.buttons {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.features {
+  display: flex;
+  align-items: center;
+  padding: 2rem 0;
+  width: 100%;
+}
+
+.featureImage {
+  height: 200px;
+  width: 200px;
+}