readme cleanup

README.md

@@ -1,68 +1,71 @@
-# Blockly Tooling
+# Adafruit IO: Block-based Actions
 
-A custom Blockly app needs to define:
+> Automation that clicks!
-- blocks
-  - inputs
-  - fields
-  - validators
-  - generators
-  - extensions
-  - mixins
-  - mutators
-- toolboxes
-  - categories
-  - buttons
-  - labels
-- workspaces
-  - starting blocks
-  - settings
-  - plugins
 
-Blockly can be difficult to work with, as given. This is a clean space to experiment.
+This repository contains the files and tooling for building the Blockly app
+that is used to create automations on Adafruit IO.
 
-**Benefits of Making a Separate Project**
+The files are organized into directories:
-- host project stays cleaner
+- `/app` the source files for the application
-- tighter code-and-fix loop
+- `/src` the tooling for developing and building the application
-- test in isolation
+- `/docs` the tooling and configuration for building the app documentation
-- deploy smaller experiments for feedback
 
-## A Framework for a custom Blockly app
+## Quick Start
 
-This is the core concept of the project: a better way of defining a custom Blockly application.
+### Setup
 
-Better?
+Node v22.x is expected, but other versions may work.
-- expressive DSL
-- keep related implementations together (Locality of Behavior)
-- higher level idioms for common interactions
 
-Check out the `/app` directory:
+```sh
-- `/app/blocks`
+git clone https://github.com/adafruit/io-actions
-- `/app/toolbox`
+cd io-actions
-- `/app/workspaces`
+npm i
+npm start
+```
 
-## Tools
+### Exporting
 
-### Transformer
+Export a Blockly application:
+```sh
+npm run export:app
+```
 
-Compiles a directory tree of DSL files into Blockly source files. This is where the main app is.
+Export the documentation site:
+```sh
+npm run docs:export
+```
 
-### Dev Environment
 
-Provides a web application to host the Blockly project under development. Combines the Transformer with Vite to automatically compile and serve the app. The expressivity and ergonomics of the DSL coupled with this environment which instantly visualize changes as they are made is the point of this project: a reaosonable Blockly dev environment.
+## Application Files
 
-- lives in `/src`
+Our custom Blockly application lives at `/app`
-- ingets from `/app`
-- hosts app at `http://localhost:5173` (or something)
 
-### Exporter
+This is where we create new workspaces, toolboxes, and blocks, as well as block
+elements like fields, inputs, mixins, validators, generators, etc.
 
-A brutal chunk of code to produce deployment-ready Blockly source files. Currently rough and ready, but effective. Lots of options should be supported but aren't.
+**TODO: info about generating, editing, and testing definition files**
 
-- lives in `/exporter`
-- ingests from `/app`
-- exports to `/export`
 
-- `/app`: custom Blockly app in development
+## Docs
-- `/src`: the Blockly Tool application
+
-- `/export`: where app files go when an export is performed
+Our documentation site is a VitePress install that lives at `/docs`
-- `/dist`: where Blockly Tool app files go when exporting this application for testing and demonstration purposes
+
+We run a task to generate the docs site markdown files based on the definition
+files from `/app`.
+
+**TODO: info about generating, testing, and deploying the docs site**
+
+
+## Developer Tooling
+
+All of our custom tooling lives at `/src`
+
+These are the files that translate and bundle our easy definition formats into
+full Blockly application bundles.
+
+Some benefits of this tooling include:
+- expressive DSL: block definitions look like the blocks they create
+- keep related things together ([Locality of Behavior](https://htmx.org/essays/locality-of-behaviour/))
+- higher-level idioms for common interactions
+
+**TODO: more info about how the dev tooling is organized and extended**