Merge pull request #72 from QURIresearch/components-in-docs

Components in docs

.github/workflows/ci.yaml

@@ -79,7 +79,9 @@ jobs:
         working-directory: packages/website
     steps:
     - uses: actions/checkout@v2
-    - name: Install dependencies
+    - name: Install dependencies from monorepo level
-      run: yarn
+      run: cd ../../ && yarn
+    - name: Build rescript in squiggle-lang
+      run: cd ../squiggle-lang && yarn build
     - name: Build website assets
       run: yarn build

packages/components/src/spec-distributions.json

@@ -84,7 +84,8 @@
           "y": { "scale": "yscale", "field": "y" },
           "y2": { "scale": "yscale", "value": 0 },
           "fill": {
-            "signal": "{gradient: 'linear', x1: 1, y1: 1, x2: 0, y2: 1, stops: [ {offset: 0.0, color: 'steelblue'}, {offset: clamp(mousex, 0, 1), color: 'steelblue'}, {offset: clamp(mousex, 0, 1), color: 'blue'}, {offset: 1.0, color: 'blue'} ] }"
+            "signal": "{gradient: 'linear', x1: 1, y1: 1, x2: 0, y2: 1, stops: [ {offset: 0.0, color: '#11ac8f'}, {offset: clamp(mousex, 0, 1), color: '#11ac8f'}, {offset: clamp(mousex, 0, 1), color: '#1b6fac'}, {offset: 1.0, color: '#1b6fac'} ] }",
+            "color": "#000"
           },
           "interpolate": { "value": "monotone" },
           "fillOpacity": { "value": 1 }

packages/squiggle-lang/README.md

@@ -81,3 +81,9 @@ complicated, as it has to return either a number, or a distribution, or even
 a representation of a function of distributions. Currently the export is simply
 the generated type that rescript creates, and can be quite confusing. We therefore
 highly recommend the use of typescript when creating tests or using this package.
+
+## Potential Issues
+If you experiment with generating different types of .gen.ts files and similar, note that they won't be caught by git (because they are in .gitignore). Make sure you delete these extra files, once they are unecessary.
+```
+    rm src/rescript/**/*.gen.ts
+```

packages/website/babel.config.js

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

packages/website/docs/Functions.mdx

@@ -0,0 +1,114 @@
+---
+sidebar_position: 7
+---
+
+import { SquiggleEditor } from '../src/components/SquiggleEditor'
+
+# Squiggle Functions Reference
+
+## Distributions
+
+### Normal distribution
+
+The `normal(mean, sd)` function creates a normal distribution with the given mean
+and standard deviation.
+
+<SquiggleEditor initialSquiggleString="normal(5, 1)" />
+
+### Uniform distribution
+
+The `uniform(low, high)` function creates a uniform distribution between the
+two given numbers.
+
+<SquiggleEditor initialSquiggleString="uniform(3, 7)" />
+
+
+### Lognormal distribution
+
+The `lognormal(mu, sigma)` returns the log of a normal distribution with parameters
+mu and sigma. The log of lognormal(mu, sigma) is a normal distribution with parameters
+mean mu and standard deviation sigma.
+
+<SquiggleEditor initialSquiggleString="lognormal(0, 0.7)" />
+
+An alternative format is also available. The "to" notation creates a lognormal
+distribution with a 90% confidence interval between the two numbers. We add
+this convinience as lognormal distributions are commonly used in practice.
+
+<SquiggleEditor initialSquiggleString="2 to 10" />
+
+Furthermore, it's also possible to create a lognormal from it's actual mean
+and standard deviation, using `lognormalFromMeanAndStdDev`.
+
+<SquiggleEditor initialSquiggleString="lognormalFromMeanAndStdDev(20, 10)" />
+
+
+### Beta distribution
+
+The `beta(a, b)` function creates a beta distribution with parameters a and b:
+
+<SquiggleEditor initialSquiggleString="beta(20, 20)" />
+
+### Exponential distribution
+
+The `exponential(mean)` function creates an exponential distribution with the given
+mean.
+
+<SquiggleEditor initialSquiggleString="exponential(1)" />
+
+
+### The Triangular distribution
+
+The `triangular(a,b,c)` function creates a triangular distribution with lower
+bound a, mode b and upper bound c.
+
+<SquiggleEditor initialSquiggleString="triangular(1, 2, 4)" />
+
+### Multimodal distriutions
+
+The multimodal function combines 2 or more other distributions to create a weighted
+combination of the two. The first positional arguments represent the distributions
+to be combined, and the last argument is how much to weigh every distribution in the
+combination.
+
+<SquiggleEditor initialSquiggleString="mm(uniform(0,1), normal(1,1), [0.5, 0.5])" />
+
+It's possible to create discrete distributions using this method.
+
+<SquiggleEditor initialSquiggleString="mm(0, 1, [0.2,0.8])" />
+
+As well as mixed distributions:
+
+<SquiggleEditor initialSquiggleString="mm(3, 8, 1 to 10, [0.2, 0.3, 0.5])" />
+
+## Other Functions
+
+### PDF of a distribution
+The `pdf(distribution, x)` function returns the density of a distribution at the
+given point x.
+
+<SquiggleEditor initialSquiggleString="pdf(normal(0,1),0)" />
+
+### Inverse of a distribution
+
+The `inv(distribution, prob)` gives the value x or which the probability for all values
+lower than x is equal to prob. It is the inverse of `cdf`.
+
+<SquiggleEditor initialSquiggleString="inv(normal(0,1),0.5)" />
+
+### CDF of a distribution
+
+The `cdf(distribution,x)` gives the cumulative probability of the distribution
+or all values lower than x. It is the inverse of `inv`.
+
+<SquiggleEditor initialSquiggleString="cdf(normal(0,1),0)" />
+
+### Mean of a distribution
+The `mean(distribution)` function gives the mean (expected value) of a distribution.
+
+<SquiggleEditor initialSquiggleString="mean(normal(5, 10))" />
+
+### Sampling a distribution
+The `sample(distribution)` samples a given distribution.
+
+<SquiggleEditor initialSquiggleString="sample(normal(0, 10))" />

packages/website/docs/Future-Features.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 3
+sidebar_position: 4
 ---
 
 # Future Features
@@ -77,5 +77,34 @@ Right now, Monte Carlo simulations are totally random. It would be nicer to be a
 - Possibly a decent web GUI (a much more advanced playground).
 - A VS Code extention and similar.
 
-## Fixes
+## Bugs
 - Discrete distributions are particularly buggy. Try ``mm(1,2,3,4,5,6,7,8,9,10) .* (5 to 8)``
+
+## New Functions
+
+### Distributions
+```js
+cauchy()
+pareto()
+metalog()
+```
+
+Possibly change mm to mix, or mx(). Also, change input format, maybe to mx([a,b,c], [a,b,c]).
+
+
+### Functions
+```js
+samples(distribution, n)
+toPdf(distribution)
+toCdf(distribution)
+toHash(distribution)
+trunctate(distribution, leftValue, rightValue)
+leftTrunctate(distribution, leftValue)
+rightTrunctate(distribution, rightValue)
+distributionFromSamples(array, params)
+distributionFromPoints()
+distributionFromHash()
+```
+
+
+

packages/website/docs/Introduction.md

@@ -0,0 +1,10 @@
+---
+sidebar_position: 1
+---
+
+# Squiggle
+
+Squiggle is a language for writing calculations under uncertainty. It has use
+cases in forecasting and writing better evaluations.
+
+The best way to get started with Squiggle is to [try it out yourself](https://playground.squiggle-language.com/).

packages/website/docs/Javscript-library.md

@@ -1,16 +1,36 @@
 ---
-sidebar_position: 2
+sidebar_position: 3
 ---
 
-# Javascript Library
+# Javascript Libraries
 
-There's a very simple javscript library for Squiggle here: https://www.npmjs.com/package/squiggle-experimental.
+There are two JavaScript packages currently available for Squiggle:
+ - [`@quri/squiggle-lang`](https://www.npmjs.com/package/@quri/squiggle-lang)
+ - [`@quri/squiggle-components`](https://www.npmjs.com/package/@quri/squiggle-components)
 
-You can see it live on this Observable page: [https://observablehq.com/d/a99e822870c4ca5f](https://observablehq.com/d/a99e822870c4ca5f).
+Types are available for both packages.
 
+## Squiggle Language
 
-## Simple Example
+The `@quri/squiggle-lang` package exports a single function, `run`, which given
-```
+a string of Squiggle code, will execute the code and return any exports and the
-let squiggle = require("squiggle-experimental@0.1.9/dist/index.js")
+environment created from the squiggle code.
-squiggle.runMePlease("3 + normal(50,1))
+
-```
+`run` has two optional arguments. The first optional argument allows you to set
+sampling settings for Squiggle when representing distributions. The second optional
+argument allows you to pass an environment previously created by another `run`
+call. Passing this environment will mean that all previously declared variables
+in the previous environment will be made available.
+
+The return type of `run` is a bit complicated, and comes from auto generated js
+code that comes from rescript. I highly recommend using typescript when using
+this library to help navigate the return type.
+
+## Squiggle Components
+
+The `@quri/squiggle-components` package offers several components and utilities
+for people who want to embed Squiggle components into websites. This documentation
+relies on `@quri/squiggle-components` frequently. 
+
+We host [a storybook](https://components.squiggle-language.com/) with details
+and usage of each of the components made available.

packages/website/docs/Language.md

@@ -1,67 +0,0 @@
----
-sidebar_position: 1
----
-
-# Squiggle Language
-
-## Distributions
-```js
-normal(a,b)
-uniform(a,b)
-lognormal(a,b)
-lognormalFromMeanAndStdDev(mean, stdev)
-beta(a,b)
-exponential(a)
-triangular(a,b,c)
-mm(a,b,c, [1,2,3]) //todo: change to mix, or mx(). Also, change input format, maybe to mx([a,b,c], [a,b,c]).
-cauchy() //todo
-pareto() //todo
-metalog() //todo
-```
-
-## Functions
-```js
-pdf(distribution, float)
-inv(distribution, float)
-cdf(distribution, float)
-mean(distribution)
-sample(distribution)
-scaleExp(distribution, float)
-scaleMultiply(distribution, float)
-scaleLog(distribution, float)
-samples(distribution, n) //todo
-toPdf(distribution) //todo
-toCdf(distribution) //todo
-toHash(distribution) //todo. Make hash of content, like, {xs:[], ys:[]}
-trunctate(distribution, leftValue, rightValue) //todo
-leftTrunctate(distribution, leftValue) //todo
-rightTrunctate(distribution, rightValue) //todo
-distributionFromSamples(array, params) //todo
-distributionFromPoints() //todo
-distributionFromHash() //todo
-log() //todo
-
-```
-
-## Example Functions
-
-```js
-ozzie_estimate(t) = lognormal({mean: 3 + (t+.1)^2.5, stdev: 8})
-nuño_estimate(t) = lognormal({mean: 3 + (t+.1)^2, stdev: 10})
-combined(t) = mm(ozzie_estimate(t) .+ nuño_estimate(t))
-combined
-```
-
-```js
-us_economy_2018 = (10.5 to 10.9)T
-growth_rate = 1.08 to 1.2
-us_economy(t) = us_economy_2018 * (growth_rate^t)
-
-us_population_2019 = 320M to 330M
-us_population_growth_rate = 1.01 to 1.1
-us_population(t) = us_population_2019 * (us_population_growth_rate^t)
-gdp_per_person(t) = us_economy(t)/us_population(t)
-gdp_per_person
-
-gdp_per_person
-```

packages/website/docs/Language.mdx

@@ -0,0 +1,36 @@
+---
+sidebar_position: 2
+---
+
+import { SquiggleEditor } from '../src/components/SquiggleEditor'
+
+# Squiggle Language
+
+The squiggle language has a very simple syntax. The best way to get to understand
+it is by simply looking at examples.
+
+## Basic Language 
+
+As an example:
+
+<SquiggleEditor initialSquiggleString={`value_of_work = 10 to 70
+value_of_work`} />
+
+Squiggle can declare variables (`value_of_work = 10 to 70`) and declare exports
+(the lone `value_of_work` line). Variables can be used later in a squiggle program
+and even in other notebooks! 
+
+An export is rendered to the output view so you can see your result.
+
+the exports can be expressions, such as:
+
+<SquiggleEditor initialSquiggleString="normal(0,1)" />
+
+## Functions
+
+Squiggle supports functions, including the rendering of functions:
+
+<SquiggleEditor initialSquiggleString={`ozzie_estimate(t) = lognormal({mean: 3 + (t+.1)^2.5, stdev: 8})
+ozzie_estimate
+`} />
+

packages/website/docs/Three-Types-Of-Distributions.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 4
+sidebar_position: 5
 ---
 
 # Three Formats of Distributions

packages/website/docusaurus.config.js

@@ -3,18 +3,35 @@
 
 const lightCodeTheme = require('prism-react-renderer/themes/github');
 const darkCodeTheme = require('prism-react-renderer/themes/dracula');
+const path = require('path');
 
 /** @type {import('@docusaurus/types').Config} */
 const config = {
   title: 'Squiggle (alpha)',
-  tagline: "Scorable programming, for use by forecasters",
+  tagline: "Estimation language for forecasters",
-  url: 'https://squiggle-documentation.netlify.app',
+  url: 'https://squiggle-language.com',
   baseUrl: '/',
   onBrokenLinks: 'throw',
   onBrokenMarkdownLinks: 'warn',
   favicon: 'img/favicon.ico',
-  organizationName: 'QURI', // Usually your GitHub org/user name.
+  organizationName: 'QURIResearch', // Usually your GitHub org/user name.
-  projectName: 'Squiggle', // Usually your repo name.
+  projectName: 'squiggle', // Usually your repo name.
+
+  plugins: [
+    () => ({
+      configureWebpack(config, isServer, utils, content) {
+        return {
+            resolve: {
+              alias : {
+                "@quri/squiggle-components": path.resolve(__dirname, "../components/src"),
+                "@quri/squiggle-lang": path.resolve(__dirname, "../squiggle-lang/src/js")
+              }
+            }
+
+        };
+      }
+    })
+  ],
 
   presets: [
     [
@@ -51,7 +68,7 @@ const config = {
         items: [
           {
             type: 'doc',
-            docId: 'Language',
+            docId: 'Introduction',
             position: 'left',
             label: 'Documentation',
           },

packages/website/src/components/SquiggleEditor.jsx

@@ -0,0 +1,13 @@
+import BrowserOnly from '@docusaurus/BrowserOnly';
+
+export function SquiggleEditor(props) {
+  return (
+    <BrowserOnly fallback={<div>Loading...</div>}>
+      {() => {
+        const LibComponent =
+          require('@quri/squiggle-components').SquiggleEditor;
+        return <LibComponent {...props} />;
+      }}
+    </BrowserOnly>
+  );
+}