Update project READMEs and contributor list for webstepper (#115)

CHANGELOG.md

@@ -41,6 +41,7 @@ and adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 - Disabled download buttons when there is no input/output.
 - Added a dialog to the file input section.
 - Made improvements to the dark mode version of the website.
+- Updated project READMEs.
 
 ### 🔧 Internal changes
 

README.md

@@ -1,133 +1,104 @@
-# MemoryViz: Creating memory model diagrams
+# MemoryViz
 
-This package generates memory model diagrams for Python code in the style of CSC110/111/148 at the University of Toronto.
-This uses the [Rough.js](https://roughjs.com/) Javascript library to emulate the look of hand-drawn diagrams.
+Welcome to the repository for the MemoryViz project!
+MemoryViz is a visualization tool that generates memory model diagrams for Python code, aimed at students and educators.
+MemoryViz is written in Javascript and is built on top of the [Rough.js](https://roughjs.com/) library.
 
-**Note**: this project is currently experimental, and may undergo significant changes before stabilizing.
+For more information, check out our [demo](https://www.cs.toronto.edu/~david/memory-viz/demo/) [project documentation](https://www.cs.toronto.edu/~david/memory-viz/).
 
-## Installation (users)
+## Installation
 
-1. Install [Node.js](https://nodejs.org/en/).
-2. Install the `memory-viz` package:
+Install MemoryViz using `npm` (requires [Node.js](https://nodejs.org/en) to be installed):
 
-    ```console
-    $ npm install memory-viz
-    ```
-
-## Sample usage
+```console
+$ npm install memory-viz
+```
 
-Running the following file:
+## Example
 
-```js
-const { draw } = require("memory-viz");
+Given a JSON file [`demo.json`](examples/demo.json) that encodes a state of Python memory and some styling options:
 
-const objects = [
+```json
+[
     {
-        type: ".frame",
-        name: "__main__",
-        id: null,
-        value: { lst1: 82, lst2: 84, p: 99, d: 10, t: 11 },
+        "type": ".frame",
+        "name": "__main__",
+        "id": null,
+        "value": { "lst1": 82, "lst2": 84, "p": 99, "d": 10, "t": 11 }
     },
     {
-        type: "str",
-        id: 19,
-        value: "David is cool!",
-        style: ["highlight"],
+        "type": "str",
+        "id": 19,
+        "value": "David is cool!",
+        "style": ["highlight"]
     },
     {
-        type: "int",
-        id: 13,
-        value: 7,
-    },
-];
-
-const m = draw(objects, true, { width: 1300 });
-
-m.save("simple_demo.svg");
+        "type": "int",
+        "id": 13,
+        "value": 7
+    }
+]
 ```
 
-produces a file `simple_demo.svg` that looks like the following:
-
-![Sample usage svg output](docs/docs/99-api/examples/simple_demo/simple_demo.svg)
-
-For more information, check out the project [documentation website](https://www.cs.toronto.edu/~david/memory-viz/) and [demo](https://www.cs.toronto.edu/~david/memory-viz/demo/).
-
-### MemoryViz CLI
-
-To use the MemoryViz CLI, run:
+you can run the following command in the terminal:
 
 ```console
-$ npx memory-viz <path-to-file>
+$ npx memory-viz --output demo_output.svg demo.json
 ```
 
-where `<path-to-file>` is the path to a file containing MemoryViz-compatible JSON. If a file path is not provided, the CLI will take input from standard input.
+This producs an SVG file, `demo_output.svg`, that visualizes the state of memory:
 
-You may also specify an output path using the `--output` option (see documentation). If no output path is provided, the CLI will print to standard output.
+![Sample usage svg output](examples/memory-viz-cli/demo_output.svg)
 
-_Note_: The CLI currently does not support typing input directly into the terminal. Instead, use piping or other strategies to pass data into standard input.
+## About this repository
 
-For more information, check out the project [documentation website](https://www.cs.toronto.edu/~david/memory-viz/docs/cli).
+This repository contains multiple [npm workspaces](https://docs.npmjs.com/cli/v7/using-npm/workspaces) that contains the MemoryViz-related projects.
+
+- [memory-viz/](memory-viz/) is the source code for the main `memory-viz` Javascript package
+- [demo/](demo/) contains the source code for the [demo website](https://www.cs.toronto.edu/~david/memory-viz/demo/)
+- [docs/](docs/) contains the source code for the [project documentation website](https://www.cs.toronto.edu/~david/memory-viz/)
+- [webstepper/](webstepper/) contains the source code for the Webstepper project, which integrates MemoryViz and [PythonTA](https://www.cs.toronto.edu/~david/pyta/)
 
 ## Developers
 
 ### Installation
 
-1. First, clone this repository.
-2. Install [Node.js](https://nodejs.org/en/).
-3. Open a terminal in your local code of the repository, and then run:
+1. Install [Node.js](https://nodejs.org/en/).
+2. Clone the MemoryViz repository and `cd` into it:
 
     ```console
-    $ npm install
+    $ git clone https://github.com/david-yz-liu/memory-viz.git
+    $ cd memory-viz
     ```
 
-4. Compile the Javascript assets using [webpack](https://webpack.js.org/guides/getting-started/):
+3. Install the dependencies:
 
     ```console
-    $ npm run build-dev --workspace=memory-viz
+    $ npm install
     ```
 
-5. Install the pre-commit hooks to automatically format your code when you make commits:
+4. Install the pre-commit hooks to automatically format your code when you make commits:
 
     ```console
     $ npx husky init
     ```
 
-### Automatic Javascript compilation
+5. Compile the MemoryViz library:
 
-Rather than running `npm run build-dev` to recompile your Javascript bundle every time you make a change, you can instead run the following command:
-
-```console
-$ npm run watch --workspace=memory-viz
-```
-
-This will use `webpack` to watch for changes to the Javascript source files and recompile them automatically.
-
-_Note_: this command will keep running until you manually terminate it (Ctrl + C), and so you'll need to open a new terminal window to enter new terminal commands like running the demo below.
-
-### Running tests
+    ```console
+    $ npm run build-dev --workspace=memory-viz
+    ```
 
-To run the test suite, execute the following command:
+6. Run the test suite to check that all tests pass:
 
-```console
-$ npm run test --workspace=memory-viz
-```
+    ```console
+    $ npm test
+    ```
 
 ### Building and running the documentation website
 
 See [`docs/README.md`](docs/README.md).
 
 ### Building and running the demo website
 
-1. First, build the assets using Webpack:
-
-    ```console
-    $ npm run build-dev --workspace=memory-viz-demo
-    ```
-
-2. Then run the website:
-
-    ```console
-    $ npm run start --workspace=memory-viz-demo
-    ```
-
-3. Visit the website at `http://localhost:9000`.
+See [`demo/README.md`](demo/README.md).

demo/README.md

@@ -0,0 +1,23 @@
+# MemoryViz Demo Website
+
+This folder contains the source code for the MemoryViz demo website.
+
+## Developers
+
+To run the demo website locally, follow these instructions from the `memory-viz/demo/` folder.
+
+_Note_: you can instead run the commands in the root project directory by adding the argument `--workspace=demo`.
+
+1. First, build the assets using Webpack:
+
+    ```console
+    $ npm run build-dev
+    ```
+
+2. Then run the website:
+
+    ```console
+    $ npm start
+    ```
+
+3. Visit the website at `http://localhost:9000`.

docs/README.md

@@ -1,24 +1,22 @@
-# Website
+# MemoryViz Documentation Website
 
 This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
 
-### Installation
+The commands described in this README assume your current working directory is `memory-viz/docs`.
+You can instead run them in the root project directory by adding the argument `--workspace=docs`.
 
-```
-$ npm install
-```
+## Local Development
 
-### Local Development
-
-```
-$ npm run start
+```console
+$ npm start
 ```
 
-This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+This command starts a local development server and opens up a browser window.
+Most changes are reflected live without having to restart the server.
 
-### Build
+## Build
 
-```
+```console
 $ npm run build
 ```
 
@@ -28,13 +26,13 @@ This command generates static content into the `build` directory and can be serv
 
 Using SSH:
 
-```
+```console
 $ USE_SSH=true npm run deploy
 ```
 
 Not using SSH:
 
-```
+```console
 $ GIT_USER=<Your GitHub username> npm run deploy
 ```
 

examples/memory-viz-api/demo.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+
+// Import draw function
+const { draw } = require("memory-viz");
+
+// Define the data to visualize
+const objects = [
+    {
+        type: ".frame",
+        name: "__main__",
+        id: null,
+        value: { lst1: 82, lst2: 84, p: 99, d: 10, t: 11 },
+    },
+    {
+        type: "str",
+        id: 19,
+        value: "David is cool!",
+        style: ["highlight"],
+    },
+    {
+        type: "int",
+        id: 13,
+        value: 7,
+    },
+];
+
+// Visualize the data, using an automated layout, and with an image width of 1300px
+const model = draw(objects, true, { width: 1300 });
+
+// Save the visualization to demo_output.svg
+model.save("demo_output.svg");

examples/memory-viz-browser/index.html

@@ -0,0 +1,47 @@
+<!doctype html>
+<html>
+    <head>
+        <meta charset="UTF-8" />
+        <title>MemoryViz in the Browser!</title>
+        <!-- Load MemoryViz from a CDN. You can substitute a local memory-viz.bundle.js. -->
+        <script
+            type="text/javascript"
+            src="https://cdn.jsdelivr.net/npm/memory-viz@latest/dist/memory-viz.bundle.js"
+        ></script>
+        <!-- Visualize the canvas. -->
+        <script type="text/javascript">
+            document.addEventListener("DOMContentLoaded", () => {
+                const canvas = document.getElementById("memory-viz-output");
+                const objects = [
+                    {
+                        type: ".frame",
+                        name: "__main__",
+                        id: null,
+                        value: { lst1: 82, lst2: 84, p: 99, d: 10, t: 11 },
+                    },
+                    {
+                        type: "str",
+                        id: 19,
+                        value: "David is cool!",
+                        style: ["highlight"],
+                    },
+                    {
+                        type: "int",
+                        id: 13,
+                        value: 7,
+                    },
+                ];
+
+                const model = memoryViz.draw(objects, true, { width: 1300 });
+                model.render(canvas);
+            });
+        </script>
+    </head>
+
+    <body>
+        <h1>A minimal example of MemoryViz in the browser</h1>
+        <div>
+            <canvas id="memory-viz-output" width="1300" height="800"></canvas>
+        </div>
+    </body>
+</html>

examples/memory-viz-cli/README.md

@@ -0,0 +1,5 @@
+# MemoryViz CLI Demo
+
+In this folder, run the command `npx memory-viz --output my_output.svg demo.json`.
+
+This will generate a file `my_output.svg` with the same contents as `demo_output.svg`.

examples/memory-viz-cli/demo.json

@@ -0,0 +1,19 @@
+[
+    {
+        "type": ".frame",
+        "name": "__main__",
+        "id": null,
+        "value": { "lst1": 82, "lst2": 84, "p": 99, "d": 10, "t": 11 }
+    },
+    {
+        "type": "str",
+        "id": 19,
+        "value": "David is cool!",
+        "style": ["highlight"]
+    },
+    {
+        "type": "int",
+        "id": 13,
+        "value": 7
+    }
+]