feat: move usage to docs (#86)

gosling-lang · Oct 27, 2023 · bc9c14f · bc9c14f
1 parent b59cc1c
commit bc9c14f
Show file tree

Hide file tree

Showing 5 changed files with 115 additions and 98 deletions.
diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -5,7 +5,9 @@ slug: /
 
 Gosling.js is a declarative grammar for interactive (epi)genomics visualization on the Web.
 
-To get started with Gosling, we recommend going through the [Create Single Track Visualization Tutorial](/tutorials). Then, you can explore examples in the [online editor](https://gosling.js.org), go through the [grammar guide](category/grammar-guide), and start building your own Gosling visualizations using the the [grammar reference](reference) and [Javascript API](js-api) parts of the documentation as a reference. 
+To get started with Gosling, we recommend going through the [Create Single Track Visualization Tutorial](/tutorials). Then, you can explore examples in the [online editor](https://gosling.js.org), go through the [grammar guide](category/grammar-guide), and start building your own Gosling visualizations using the the [grammar reference](reference) and [Javascript API](js-api) documentation. 
+
+Please see [usage guide](usage) to learn about all the contexts in which Gosling can be used. 
 
 ## What is a grammar for data visualization?
 Words are combined together into sentences based on their parts of speech and grammar rules. In a similar way, visual components (such as a coordinate axis, plot markers, and legend) have specific roles and are combined according to certain rules. You probably know these rules without realizing it! These roles and rules have been made explicit such as in the [Grammar of Graphics](https://link.springer.com/book/10.1007/0-387-28695-0).

diff --git a/docs/usage.md b/docs/usage.md
@@ -0,0 +1,108 @@
+---
+title: Usage
+---
+
+# Usage
+
+Gosling can be used and deployed in a variety of contexts.
+
+- In the [online editor](#online-editor)
+- In Python using [Gos](https://gosling-lang.github.io/gos/)
+- In a [HTML page](#html)
+- In a [React application](#react)
+
+## Online Editor
+
+You can visit the [online editor](https://gosling.js.org) to start trying Gosling immediately.
+
+### Load a Gosling Spec From Your Github Gist
+
+1. To load a spec you first have to create a gist with a file named gosling.js\* that specifies the spec.
+1. You can additionally specify a `readme.md` file to describe your spec.
+1. Also be sure to give your gist a fabulous title. It'll be shown in the gosling editor.
+   You can then open your visualization at <a>http://<editor_url>/?gist=<github_username>/<gist_id></a>.
+   <!-- For example, https://gosling.js.org/?gist=flekschas/e6e388332814886d4d714efd0e88093b -->
+   For example, https://gosling.js.org/?gist=wangqianwen0418/1cc79f00990806f07b379ae6a7c7b7b3
+
+## HTML
+
+Gosling can be embedded directly into your HTML page by adding gosling.js and several other dependencies in script tags.
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+    <title>Gosling Visualization</title>
+    <link rel="stylesheet" href="https://esm.sh/higlass@1.13/dist/hglib.css">
+    <script type="importmap">
+      {
+        "imports": {
+          "react": "https://esm.sh/react@18",
+          "react-dom": "https://esm.sh/react-dom@18",
+          "pixi": "https://esm.sh/pixi.js@6",
+          "higlass": "https://esm.sh/higlass@1.13?external=react,react-dom,pixi",
+          "gosling.js": "https://esm.sh/gosling.js@0.11.0?external=react,react-dom,pixi,higlass"
+        }
+      }
+    </script>
+</head>
+<body>
+    <div id="gosling-container"></div>
+    <script type="module">
+        import { embed } from 'gosling.js';
+        embed(document.getElementById('gosling-container'), {
+        "tracks": [
+          {
+            "data": {
+              "url": "https://server.gosling-lang.org/api/v1/tileset_info/?d=cistrome-multivec",
+              "type": "multivec",
+              "row": "sample",
+              "column": "position",
+              "value": "peak",
+              "categories": ["sample 1"],
+            },
+            "mark": "rect",
+            "x": { "field": "position", "type": "genomic" },
+            "color": { "field": "peak", "type": "quantitative", "legend": true },
+            "width": 600,
+            "height": 130,
+          },
+        ],
+      });
+    </script>
+  </body>
+</html>
+```
+
+## React
+
+Beginning with version 0.9.30, Gosling now supports React v18 (You can still use React v16 or v17).
+If you are using a Gosling version prior to 0.9.30, please continue to use React v16.
+
+Install `gosling.js` and its dependent libraries:
+
+```sh
+yarn add gosling.js higlass pixi.js react@18 react-dom@18
+```
+
+Add the following stylesheet to your base `html` file:
+
+```html
+<head>
+  <link
+    rel="stylesheet"
+    href="https://esm.sh/higlass@1.13/dist/hglib.css"
+  />
+</head>
+```
+
+Use the Gosling.js' react component to visualize your data:
+
+```js
+import { GoslingComponent } from "gosling.js";
+function App() {
+  return <GoslingComponent spec={yourSpec} />;
+}
+```
+
+Please visit [gosling-react](https://github.com/gosling-lang/gosling-react) to find detailed instruction on using React.
diff --git a/docusaurus.config.js b/docusaurus.config.js
@@ -45,7 +45,6 @@ module.exports = {
           position: 'left',
         },
         { to: 'tutorials/', label: 'Tutorials', position: 'left' },
-        { to: 'usage/', label: 'Usage', position: 'left' },
         { to: 'examples/', label: 'Examples', position: 'left' },
         { to: 'themes/', label: 'Themes', position: 'left' },
         { to: 'about/', label: 'About', position: 'left' },

diff --git a/sidebarDocs.js b/sidebarDocs.js
@@ -4,6 +4,10 @@ module.exports = {
       type: 'doc',
       id: 'getting-started',
     },
+    {
+      type: 'doc',
+      id: 'usage'
+    },
     {
       type: 'category',
       label: 'Grammar Guide',

diff --git a/src/pages/usage/index.md b/src/pages/usage/index.md