Update documentation in preparation for next release (#276)

# Problem

Our docs need an overhaul to reflect the upcoming release

# Solution

This is a big PR so I'll try to break things down.

First of all here's what our new sidebar looks like:
![Screenshot 2024-11-16 at 9 07
23 AM](https://github.com/user-attachments/assets/4560cd03-89b0-415e-a8a2-6f1d120ac51c)

And here's a summary of the changes:
1. Introduced `code-samples` package to the root of the repo. 
1. This is a package containing various examples for use in our
documentation. The kicker is these are run through analysis and linting
just like any of our other Luau code, so our code samples in docs are
easy to validate for correctness. It can also be synced to Studio and
all of the included stories can be viewed in Flipbook
3. Docs on writing stories have been rewritten
4. Updated docs on our Story/Storybook formats to reflect changes from
Storyteller
5. Docs have been added for writing React, Fusion, and Roact stories
along with tabs to switch to Storyteller variants
6. Updated docs for contributors
7. Minor change to our build script which now makes sure Flipbook's
storybook does not leak through to prod builds

# Checklist

- [x] Ran `lune run test` locally before merging

.gitignore

@@ -10,9 +10,9 @@ sourcemap*.json
 globalTypes.d.luau
 
 # Wally
-/DevPackages
-/Packages
-/wally.lock
+DevPackages
+Packages
+wally.lock
 
 # Other
 /*.log

.lune/analyze.luau

@@ -28,3 +28,12 @@ run("luau-lsp", {
 	constants.LUNE_SCRIPTS_PATH,
 	constants.EXAMPLE_PATH,
 })
+
+run("luau-lsp", {
+	"analyze",
+	`--sourcemap={constants.SOURCEMAP_PATH}`,
+	`--defs={globalDefsPath}`,
+	"--settings=./.vscode/settings.json",
+	"--ignore=**/_Index/**",
+	"code-samples/src",
+})

.lune/build.luau

@@ -15,14 +15,20 @@ assert(target == "dev" or target == "prod", `bad value for target (must be one o
 local output = if args.output then args.output else `{getPluginsPath(process.os)}/{constants.PLUGIN_FILENAME}`
 assert(typeof(output) == "string", `bad value for output (string expected, got {typeof(output)})`)
 
+local PRUNED_FILES = {
+	"*.spec.luau",
+	"*.story.luau",
+	"*.storybook.luau",
+}
+
 local function build()
 	clean()
 	compile(target)
 
 	if target == "prod" then
-		run("rm", { "-rf", `{constants.BUILD_PATH}/**/*.spec.luau` })
-		run("rm", { "-rf", `{constants.BUILD_PATH}/**/*.story.luau` })
-		run("rm", { "-rf", `{constants.BUILD_PATH}/**/*.storybook.luau` })
+		for _, pattern in PRUNED_FILES do
+			run("find", { constants.BUILD_PATH, "-type", "f", "-name", pattern, "-delete" })
+		end
 	end
 
 	run("rojo", { "build", "-o", output })

.lune/lib/constants.luau

@@ -19,5 +19,6 @@ return {
 		"src",
 		".lune",
 		"example",
+		"code-samples/src",
 	},
 }

.lune/wally-install.luau

@@ -1,5 +1,19 @@
 local run = require("./lib/run")
 
-run("wally", { "install" })
-run("rojo", { "sourcemap", "build.project.json", "-o", "sourcemap.json" })
-run("wally-package-types", { "--sourcemap", "sourcemap.json", "Packages" })
+do
+	run("wally", { "install" })
+	run("rojo", { "sourcemap", "build.project.json", "-o", "sourcemap.json" })
+	run("wally-package-types", { "--sourcemap", "sourcemap.json", "Packages" })
+end
+
+do
+	run("wally", { "install" }, {
+		cwd = "code-samples",
+	})
+	run("rojo", { "sourcemap", "default.project.json", "-o", "sourcemap.json" }, {
+		cwd = "code-samples",
+	})
+	run("wally-package-types", { "--sourcemap", "sourcemap.json", "Packages" }, {
+		cwd = "code-samples",
+	})
+end

.vscode/settings.json

@@ -10,4 +10,4 @@
     "@root": "./src",
     "@lune/": "~/.lune/.typedefs/0.8.3/"
   }
-}
+}

analysis.project.json

@@ -1,15 +1,29 @@
 {
-  "name": "flipbook",
+  "name": "Analysis",
   "tree": {
-    "Lune": {
-      "$path": ".lune"
-    },
-    "TestRunner": {
-      "$path": "tests"
-    },
-    "Example": {
-      "$path": "example"
-    },
-    "$path": "build.project.json"
+    "$className": "DataModel",
+    "ReplicatedStorage": {
+      "Packages": {
+        "$path": "code-samples/Packages"
+      },
+      "CodeSamples": {
+        "$path": "code-samples"
+      },
+
+      "Lune": {
+        "$path": ".lune"
+      },
+
+      "Flipbook": {
+        "TestRunner": {
+          "$path": "tests"
+        },
+        "Example": {
+          "$path": "example"
+        },
+
+        "$path": "build.project.json"
+      }
+    }
   }
-}
+}

code-samples/README.md

@@ -0,0 +1,19 @@
+# code-samples
+
+Package of code samples for using flipbook. Includes example Storybooks and Stories for each supported framework.
+
+The code samples are for illustrating usage of flipbook on the docs site. This package can also be synced into Studio and viewed in the flipbook plugin.
+
+All code samples are analyzed to ensure correctness before being deployed.
+
+## Setup
+
+Run the following commands from the root of the repo.
+
+```sh
+lune run wally-install
+lune run build
+rojo serve code-samples/default.project.json
+```
+
+Open Studio and sync with Rojo. Then open flipbook to preview the code samples.

code-samples/default.project.json

@@ -0,0 +1,14 @@
+{
+  "name": "CodeSamples",
+  "tree": {
+    "$className": "DataModel",
+    "ReplicatedStorage": {
+      "Packages": {
+        "$path": "Packages"
+      },
+      "CodeSamples": {
+        "$path": "src"
+      }
+    }
+  }
+}

code-samples/src/Default/Button.story.luau

@@ -0,0 +1,18 @@
+return {
+	story = function()
+		local button = Instance.new("TextButton")
+		button.Text = "Button"
+		button.TextSize = 16
+		button.Font = Enum.Font.BuilderSansExtraBold
+		button.TextColor3 = Color3.fromRGB(50, 50, 50)
+		button.BackgroundColor3 = Color3.fromRGB(255, 255, 255)
+		button.BorderSizePixel = 0
+		button.Size = UDim2.fromOffset(200, 40)
+
+		button.Activated:Connect(function()
+			print("clicked")
+		end)
+
+		return button
+	end,
+}

code-samples/src/Default/ProjectName.storybook.luau

@@ -0,0 +1,5 @@
+return {
+	storyRoots = {
+		script.Parent,
+	},
+}

code-samples/src/Fusion/Fusion.storybook.luau

@@ -0,0 +1,13 @@
+local ReplicatedStorage = game:GetService("ReplicatedStorage")
+
+local Fusion = require(ReplicatedStorage.Packages.Fusion)
+
+return {
+	name = "Fusion",
+	storyRoots = {
+		script.Parent,
+	},
+	packages = {
+		Fusion = Fusion,
+	},
+}

code-samples/src/Fusion/FusionButton.luau

@@ -0,0 +1,24 @@
+local ReplicatedStorage = game:GetService("ReplicatedStorage")
+
+local Fusion = require(ReplicatedStorage.Packages.Fusion)
+
+local New = Fusion.New
+local OnEvent = Fusion.OnEvent
+
+local function FusionButton(props: {
+	text: string,
+	onActivated: () -> (),
+})
+	return New("TextButton")({
+		Text = props.text,
+		TextSize = 16,
+		Font = Enum.Font.BuilderSansExtraBold,
+		TextColor3 = Color3.fromRGB(50, 50, 50),
+		BackgroundColor3 = Color3.fromRGB(255, 255, 255),
+		BorderSizePixel = 0,
+		Size = UDim2.fromOffset(200, 40),
+		[OnEvent("Activated")] = props.onActivated,
+	})
+end
+
+return FusionButton

code-samples/src/Fusion/FusionButton.story.luau

@@ -0,0 +1,12 @@
+local FusionButton = require(script.Parent.FusionButton)
+
+return {
+	story = function()
+		return FusionButton({
+			text = "Click Me",
+			onActivated = function()
+				print("click")
+			end,
+		})
+	end,
+}

code-samples/src/FusionStoryteller/Fusion.storybook.luau

@@ -0,0 +1,16 @@
+local ReplicatedStorage = game:GetService("ReplicatedStorage")
+
+local Fusion = require(ReplicatedStorage.Packages.Fusion)
+local Storyteller = require(ReplicatedStorage.Packages.Storyteller)
+
+local storybook: Storyteller.Storybook = {
+	name = "Fusion (Storyteller)",
+	storyRoots = {
+		script.Parent,
+	},
+	packages = {
+		Fusion = Fusion,
+	},
+}
+
+return storybook

code-samples/src/FusionStoryteller/FusionButton.luau

@@ -0,0 +1,24 @@
+local ReplicatedStorage = game:GetService("ReplicatedStorage")
+
+local Fusion = require(ReplicatedStorage.Packages.Fusion)
+
+local New = Fusion.New
+local OnEvent = Fusion.OnEvent
+
+local function FusionButton(props: {
+	text: string,
+	onActivated: () -> (),
+})
+	return New("TextButton")({
+		Text = props.text,
+		TextSize = 16,
+		Font = Enum.Font.BuilderSansExtraBold,
+		TextColor3 = Color3.fromRGB(50, 50, 50),
+		BackgroundColor3 = Color3.fromRGB(255, 255, 255),
+		BorderSizePixel = 0,
+		Size = UDim2.fromOffset(200, 40),
+		[OnEvent("Activated")] = props.onActivated,
+	})
+end
+
+return FusionButton

code-samples/src/FusionStoryteller/FusionButton.story.luau

@@ -0,0 +1,18 @@
+local ReplicatedStorage = game:GetService("ReplicatedStorage")
+
+local Storyteller = require(ReplicatedStorage.Packages.Storyteller)
+
+local FusionButton = require(script.Parent.FusionButton)
+
+local story: Storyteller.Story<any> = {
+	story = function()
+		return FusionButton({
+			text = "Click Me",
+			onActivated = function()
+				print("click")
+			end,
+		})
+	end,
+}
+
+return story

code-samples/src/React/React.storybook.luau

@@ -0,0 +1,15 @@
+local ReplicatedStorage = game:GetService("ReplicatedStorage")
+
+local React = require(ReplicatedStorage.Packages.React)
+local ReactRoblox = require(ReplicatedStorage.Packages.ReactRoblox)
+
+return {
+	name = "React",
+	storyRoots = {
+		script.Parent,
+	},
+	packages = {
+		React = React,
+		ReactRoblox = ReactRoblox,
+	},
+}

code-samples/src/React/ReactButton.luau

@@ -0,0 +1,21 @@
+local ReplicatedStorage = game:GetService("ReplicatedStorage")
+
+local React = require(ReplicatedStorage.Packages.React)
+
+local function ReactButton(props: {
+	text: string,
+	onActivated: () -> (),
+})
+	return React.createElement("TextButton", {
+		Text = props.text,
+		TextSize = 16,
+		Font = Enum.Font.BuilderSansExtraBold,
+		TextColor3 = Color3.fromRGB(50, 50, 50),
+		BackgroundColor3 = Color3.fromRGB(255, 255, 255),
+		BorderSizePixel = 0,
+		Size = UDim2.fromOffset(200, 40),
+		[React.Event.Activated] = props.onActivated,
+	})
+end
+
+return ReactButton

code-samples/src/React/ReactButton.story copy.luau

@@ -0,0 +1,16 @@
+local ReplicatedStorage = game:GetService("ReplicatedStorage")
+
+local React = require(ReplicatedStorage.Packages.React)
+
+local ReactButton = require(script.Parent.ReactButton)
+
+return {
+	story = function()
+		return React.createElement(ReactButton, {
+			text = "Click Me",
+			onActivated = function()
+				print("click")
+			end,
+		})
+	end,
+}

code-samples/src/React/ReactButton.story.luau

@@ -0,0 +1,16 @@
+local ReplicatedStorage = game:GetService("ReplicatedStorage")
+
+local React = require(ReplicatedStorage.Packages.React)
+
+local ReactButton = require(script.Parent.ReactButton)
+
+return {
+	story = function()
+		return React.createElement(ReactButton, {
+			text = "Click Me",
+			onActivated = function()
+				print("click")
+			end,
+		})
+	end,
+}