Merge pull request #2938 from quantified-uncertainty/Doc-refactors-Jan-8

Generic doc cleanup

packages/components/src/components/SquiggleEditor.tsx

@@ -50,7 +50,7 @@ export const SquiggleEditor: FC<SquiggleEditorProps> = ({
   return (
     <div>
       <div
-        className="border border-slate-100 bg-slate-50 rounded-sm p-2"
+        className="border border-slate-300 bg-slate-50 rounded-sm p-2"
         data-testid="squiggle-editor"
       >
         <CodeEditor

packages/components/src/components/ui/FnDocumentation.tsx

@@ -68,7 +68,6 @@ export const FnDocumentation: FC<{
     description,
     definitions,
     examples,
-    interactiveExamples,
     versionAdded,
   } = documentation;
   const textSize = size === "small" ? "text-xs" : "text-sm";
@@ -170,31 +169,31 @@ export const FnDocumentation: FC<{
           </div>
         </Section>
       ) : null}
-      {examples?.length ?? interactiveExamples?.length ? (
+      {examples?.length ? (
         <Section>
           <header className={clsx("text-slate-600 font-medium mb-2", textSize)}>
             Examples
           </header>
 
           {examples &&
-            examples.map((example, i) => (
-              <MarkdownViewer
-                className="max-width-[200px]"
-                key={i}
-                md={`\`\`\`squiggle\n${example}\n\`\`\``}
-                textSize="sm"
-              />
-            ))}
-          {(interactiveExamples ?? []).map((example, i) => (
-            <div className="pt-2 pb-4" key={i}>
-              <SquiggleEditor
-                defaultCode={example}
-                key={i}
-                chartHeight={size === "small" ? 80 : 120}
-                editorFontSize={size === "small" ? 12 : 13}
-              />
-            </div>
-          ))}
+            examples.map(({ text, isInteractive }, i) =>
+              isInteractive ? (
+                <div className="pt-2 pb-4" key={i}>
+                  <SquiggleEditor
+                    defaultCode={text}
+                    chartHeight={size === "small" ? 30 : 40}
+                    editorFontSize={size === "small" ? 12 : 13}
+                  />
+                </div>
+              ) : (
+                <MarkdownViewer
+                  className="max-width-[200px]"
+                  key={i}
+                  md={`\`\`\`squiggle\n${text}\n\`\`\``}
+                  textSize="sm"
+                />
+              )
+            )}
         </Section>
       ) : null}
     </>

packages/components/src/stories/InternalComponents/FnDocumentation.stories.tsx

@@ -51,23 +51,30 @@ const exampleDocumentation: FnDocumentationType = {
   requiresNamespace: false,
   signatures: ["(number, number) => number"],
   examples: [
-    `xDist = SampleSet.fromDist(2 to 5)
+    {
+      text: `xDist = SampleSet.fromDist(2 to 5)
 yDist = normal({p5:-3, p95:3}) * 5 - xDist ^ 2
 Plot.scatter({
   xDist: xDist,
   yDist: yDist,
   xScale: Scale.log({min: 1.5}),
 })`,
-  ],
-  interactiveExamples: [
-    `xDist = SampleSet.fromDist(2 to 5)
+      isInteractive: false,
+      useForTests: false,
+    },
+    {
+      text: `xDist = SampleSet.fromDist(2 to 5)
 yDist = normal({p5:-3, p95:3}) * 5 - xDist ^ 2
 Plot.scatter({
   xDist: xDist,
   yDist: yDist,
   xScale: Scale.log({min: 1.5}),
 })`,
-    `xDist = SampleSet.fromDist(normal({p5:-2, p95:5}))
+      isInteractive: false,
+      useForTests: false,
+    },
+    {
+      text: `xDist = SampleSet.fromDist(normal({p5:-2, p95:5}))
 yDist = normal({p5:-3, p95:3}) * 5 - xDist
 Plot.scatter({
   title: "A Scatterplot",
@@ -76,6 +83,9 @@ Plot.scatter({
   xScale: Scale.symlog({title: "X Axis Title"}),
   yScale: Scale.symlog({title: "Y Axis Title"}),
 })`,
+      isInteractive: false,
+      useForTests: false,
+    },
   ],
   isExperimental: true,
   definitions: [],

packages/squiggle-lang/__tests__/library/examples_test.ts

@@ -1,19 +1,18 @@
 import { registry } from "../../src/library/registry/index.js";
 import { evaluateStringToResult } from "../../src/reducer/index.js";
 
-test.each(registry.allExamplesWithFns())(
-  "tests of example $example",
-  async ({ fn, example }) => {
-    const result = await evaluateStringToResult(example);
+test.each(
+  registry.allExamplesWithFns().filter(({ example }) => example.useForTests)
+)("tests of example $example", async ({ fn, example }) => {
+  const result = await evaluateStringToResult(example.text);
 
-    if (!result.ok) {
-      throw new Error(`Can't test type, with error: ${result.value}`);
-    }
-
-    if (fn.output !== undefined) {
-      expect(result.value.type).toEqual(fn.output);
-    }
+  if (!result.ok) {
+    throw new Error(`Can't test type, with error: ${result.value}`);
+  }
 
-    expect(result.ok).toBe(true);
+  if (fn.output !== undefined) {
+    expect(result.value.type).toEqual(fn.output);
   }
-);
+
+  expect(result.ok).toBe(true);
+});

packages/squiggle-lang/src/fr/calculator.ts

@@ -1,3 +1,4 @@
+import { makeFnExample } from "../library/registry/core.js";
 import { makeDefinition } from "../library/registry/fnDefinition.js";
 import {
   frArray,
@@ -35,16 +36,27 @@ export const library = [
     name: "make",
     output: "Calculator",
     examples: [
-      `Calculator.make(
-  {|x| x * 5},
-  {
-    title: "My great calculator",
-    inputs: [Input.text({ name: "x", default: "20" })],
-    autorun: false,
-    sampleCount: 10k,
-  }
-)`,
-      "({|x| x * 5}) -> Calculator",
+      makeFnExample(
+        `Calculator.make(
+{|text, textArea, select, checkbox| text + textArea},
+{
+  title: "My example calculator",
+  inputs: [
+    Input.text({ name: "text", default: "20" }),
+    Input.textArea({ name: "textArea", default: "50 to 80" }),
+    Input.select({ name: "select", default: "second", options: ["first", "second", "third"] }),
+    Input.checkbox({ name: "checkbox", default: true }),
+  ],
+  sampleCount: 10k,
+})`,
+        { isInteractive: true }
+      ),
+      makeFnExample(
+        `// When a calculator is created with only a function, it will guess the inputs based on the function's parameters. It won't provide default values if it's a user-written function.
+
+({|x| x * 5}) -> Calculator`,
+        { isInteractive: true }
+      ),
     ],
     description: `
 \`Calculator.make\` takes in a function, a description, and a list of inputs. The function should take in the same number of arguments as the number of inputs, and the arguments should be of the same type as the default value of the input.

packages/squiggle-lang/src/fr/common.ts

@@ -1,4 +1,5 @@
 import { REThrow } from "../errors/messages.js";
+import { makeFnExample } from "../library/registry/core.js";
 import { makeDefinition } from "../library/registry/fnDefinition.js";
 import {
   frAny,
@@ -18,6 +19,7 @@ const maker = new FnFactory({
 export const library = [
   maker.make({
     name: "equal",
+    description: `Returns true if the two values passed in are equal, false otherwise. Does not work for Squiggle functions, but works for most other types.`,
     definitions: [
       makeDefinition([frAny(), frAny()], frBool, ([a, b]) => {
         return isEqual(a, b);
@@ -36,6 +38,15 @@ export const library = [
     name: "typeOf",
     description:
       "Returns the type of the value passed in as a string. This is useful when you want to treat a value differently depending on its type.",
+    examples: [
+      makeFnExample(
+        `myString = typeOf("foo")
+myBool = typeOf(true)
+myDist = typeOf(5 to 10)
+myFn = typeOf({|e| e})`,
+        { isInteractive: true }
+      ),
+    ],
     definitions: [
       makeDefinition([frAny()], frString, ([value]) => {
         return value.publicName;