docs: initial instructions (#348)

docs/README.md

@@ -7,8 +7,9 @@ title: Introduction
 
 `nebula.js` is a collection of JavaScript libraries and APIs that helps developers integrate visualizations and mashups on top of Qlik's Associative Engine.
 
-It consists of three parts:
+It consists of :
 
 - `nucleus`: A product and framework agnostic JavaScript library for building mashups.
 - `supernova`: A JavaScript API for consuming and visualizing QIX data.
+- `snapshooter`: A JavaScript API for rendering a `supernova` in offline mode.
 - `cli`: Tools to help you create, develop and build a `supernova`.

docs/app-selections.md

@@ -0,0 +1,6 @@
+---
+id: app-selections
+title: App selections
+---
+
+TODO

docs/installation.md

@@ -0,0 +1,67 @@
+---
+id: installation
+title: Installation
+---
+
+All `nebula.js` modules are available on the public npm registry as npm packages and can be installed through either npm or as a script import.
+
+`@nebula.js/supernova` and `@nebula.js/nucleus` are the two core modules that you will be using and are required when integrating `nebula.js` on the web.
+
+## Script import
+
+The easiest way to load the modules is from a CDN like `jsdelivr`:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@nebula.js/supernova" crossorigin></script>
+<script src="https://cdn.jsdelivr.net/npm/@nebula.js/nucleus" crossorigin></script>
+```
+
+Both are UMD packages and will add the variables `supernova` and `nucleus` to the global namespace.
+
+For production, it is recommended to use a specific version of each module to avoid surprises from newer or breaking versions of the APIs:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@nebula.js/supernova@0.1.1" crossorigin></script>
+<script src="https://cdn.jsdelivr.net/npm/@nebula.js/nucleus@0.1.1" crossorigin></script>
+```
+
+## Npm or yarn
+
+If you are building your own web project using Webpack, Rollup, Parcel or similar you can install the packages with npm:
+
+```bash
+$ npm install @nebula.js/supernova @nebula.js/nucleus
+```
+
+or yarn:
+
+```bash
+$ yarn add @nebula.js/supernova @nebula.js/nucleus
+```
+
+and then import `nucleus` wherever you're using it:
+
+```js
+import nucleus from '@nebula.js/nucleus';
+```
+
+You should not need to import `@nebula.js/supernova` yourself, it is a dependency to most charts and will be resolved automatically by the bundling tool when needed.
+
+## CLI
+
+`nebula.js` provides a CLI for quickly getting started with a supernova project and provides a development server to help you during the
+development phase.
+
+```bash
+$ npm install @nebula.js/cli
+```
+
+## Development builds
+
+Some modules are available as a development build which provide more errors and warnings when detecting potentially bad usage of the APIs.
+You should only use these during the development phase of your project, never in production.
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@nebula.js/supernova@0.1.1/dist/supernova.dev.js" crossorigin></script>
+<script src="https://cdn.jsdelivr.net/npm/@nebula.js/nucleus@0.1.1/dist/nucleus.dev.js" crossorigin></script>
+```

docs/nucleus-configuration.md

@@ -0,0 +1,6 @@
+---
+id: nucleus-configuration
+title: Configuration
+---
+
+TODO

docs/render-charts.md

@@ -0,0 +1,6 @@
+---
+id: render-charts
+title: Render charts
+---
+
+TODO

docs/sn-controller.md

@@ -0,0 +1,6 @@
+---
+id: sn-controller
+title: Modify charts
+---
+
+TODO

docs/web-integration.md

@@ -0,0 +1,117 @@
+---
+id: web-integration
+title: Web integration
+---
+
+Integrating `nebula.js` with your project requires the following steps:
+
+1. Connect to a Qlik Sense deployment
+1. Load `nebula.js` core modules
+1. Load chart modules
+1. Configure nucleus
+1. Render charts
+
+## Connect to Qlik
+
+The majority of communication between the web and a Qlik Sense deployment happens with a WebSocket connection, how you authenticate and create such a connection depends on the type of deployment you want to connect to. The examples will assume you are connecting to your own Qlik Cloud Services tenant and have already [configured it to allow web integrations](https://help.qlik.com/en-US/cloud-services/Subsystems/Hub/Content/Sense_Hub/Admin/mc-adminster-web-integrations.htm).
+
+The connection needs to be created using `enigma.js` which you should load first:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/enigma.js" crossorigin></script>
+```
+
+Before creating the connection, you need to fetch a `schema` which helps `enigma.js` understand how and what methods you can use to communicate with Qlik:
+
+```js
+async function connect() {
+  const schema = await (await fetch('https://cdn.jsdelivr.net/npm/enigma.js@2.6.3/schemas/12.170.2.json')).json();
+}
+```
+
+To create the connection you need to know your QCS tenant url, the `qlik-web-integration-id` and the GUID of the document you want to open:
+
+```js
+async function connect() {
+  const schema = await (await fetch('https://cdn.jsdelivr.net/npm/enigma.js@2.6.3/schemas/12.170.2.json')).json();
+
+  const enigmaGlobal = await enigma
+    .create({
+      schema,
+      url: 'wss://<tenant>.us.qlikcloud.com/app/<GUID>?qlik-web-integration-id=<qlik-web-integration-id>',
+    })
+    .open();
+
+  const enigmaApp = await enigmaGlobal.openDoc('<GUID>');
+}
+```
+
+Read more:
+
+- [Connecting to various Qlik Sense deployments](#)
+- [enigma.js](#)
+
+## Load nebula core modules
+
+Load the two core `nebula.js` modules:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@nebula.js/supernova" crossorigin></script>
+<script src="https://cdn.jsdelivr.net/npm/@nebula.js/nucleus" crossorigin></script>
+```
+
+## Load chart modules
+
+The core modules do not contain any charts by themselves, each chart is its own separate module and needs to be loaded and registered before it can be used.
+
+Official supernova chart modules from Qlik are published under the `@nebula.js` scope and are prefixed with `sn-`.
+The available charts are as follows:
+
+- Bar chart: `@nebula.js/sn-bar-chart`
+- Line chart: `@nebula.js/sn-line-chart`
+- Pie chart: `@nebula.js/sn-pie-chart`
+- Sankey chart: `@nebula.js/sn-sankey-chart`
+- Funnel chart: `@nebula.js/sn-funnel-chart`
+- Mekko chart: `@nebula.js/sn-mekko-chart`
+
+You can load a chart through a `<script>` tag:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@nebula.js/sn-bar-chart" crossorigin></script>
+```
+
+which makes it available to you on the global `window` object as `@nebula.js/sn-bar-chart`.
+
+## Render charts
+
+Before rendering the chart you need to configure `nucleus` with the supernova types you want to support:
+
+```js
+const n = nucleus.createConfiguration({
+  types: [
+    {
+      type: 'barchart',
+      load: () => Promise.resolve(window['@nebula.js/sn-bar-chart']),
+    },
+  ],
+});
+```
+
+You can then render a chart on the fly in an `HTMLElement` that has a fixed size and provide the initial `fields` to it:
+
+```js
+n(enigmaApp).render({
+  element: document.querySelector('#chart'),
+  type: 'barchart',
+  fields: ['Product', '=sum(Sales)'],
+});
+```
+
+If the `GenericObject` already exists in the app you opened, you can render it by providing its `id`:
+
+```js
+n(enigmaApp).render({
+  element: document.querySelector('#chart'),
+  id: '<ObjectID>',
+});
+```

website/core/Footer.js

@@ -23,7 +23,7 @@ function Footer({ config, language }) {
         <div />
         <div>
           <h5>Docs</h5>
-          <a href={docUrl('introduction.html', language)}>Getting Started</a>
+          <a href={docUrl('introduction', language)}>Getting Started</a>
         </div>
         <div>
           <h5>Links</h5>

website/i18n/en.json

@@ -0,0 +1,41 @@
+{
+  "_comment": "This file is auto-generated by write-translations.js",
+  "localized-strings": {
+    "next": "Next",
+    "previous": "Previous",
+    "tagline": "A new star on the rise",
+    "docs": {
+      "app-selections": {
+        "title": "App selections"
+      },
+      "installation": {
+        "title": "Installation"
+      },
+      "nucleus-configuration": {
+        "title": "Configuration"
+      },
+      "introduction": {
+        "title": "Introduction"
+      },
+      "render-charts": {
+        "title": "Render charts"
+      },
+      "sn-controller": {
+        "title": "Modify charts"
+      },
+      "web-integration": {
+        "title": "Web integration"
+      }
+    },
+    "links": {},
+    "categories": {
+      "Getting started": "Getting started",
+      "Nucleus guide": "Nucleus guide"
+    }
+  },
+  "pages-strings": {
+    "Help Translate|recruit community translators for your project": "Help Translate",
+    "Edit this Doc|recruitment message asking to edit the doc source": "Edit",
+    "Translate this Doc|recruitment message asking to translate the docs": "Translate"
+  }
+}

website/sidebars.json

@@ -1,5 +1,6 @@
 {
   "docs": {
-    "Introduction": ["introduction"]
+    "Getting started": ["introduction", "installation", "web-integration"],
+    "Nucleus guide": ["nucleus-configuration", "render-charts", "sn-controller", "app-selections"]
   }
 }

website/siteConfig.js

@@ -25,30 +25,13 @@ const siteConfig = {
     secondaryColor: '#0f0',
   },
 
-  /* Custom fonts for website */
-  /*
-  fonts: {
-    myFont: [
-      "Times New Roman",
-      "Serif"
-    ],
-    myOtherFont: [
-      "-apple-system",
-      "system-ui"
-    ]
-  },
-  */
-
   // This copyright info is used in /core/Footer.js and blog RSS/Atom feeds.
   copyright: `Copyright © ${new Date().getFullYear()} QlikTech International AB`,
 
   highlight: {
-    // Highlight.js theme to use for syntax highlighting in code blocks.
-    theme: 'default',
+    theme: 'atom-one-light',
   },
-
-  // Add custom scripts here that would be placed in <script> tags.
-  scripts: ['https://buttons.github.io/buttons.js'],
+  usePrism: ['jsx', 'js', 'html', 'bash'],
 
   // On page navigation for the current documentation page.
   onPageNav: 'separate',

website/static/css/custom.css

@@ -1,5 +1,22 @@
 /* your custom css */
 
+body {
+  font-family: 'Source Sans Pro', Arial, Helvetica, sans-serif;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+  font-weight: 400;
+  color: #404040;
+}
+
+h1,
+h2 {
+  font-weight: 300;
+}
+
+code {
+  color: #91298c;
+}
+
 @media only screen and (min-device-width: 360px) and (max-device-width: 736px) {
 }