diff --git a/CHANGELOG.md b/CHANGELOG.md index 96305c7..af3d4a4 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/README.md b/README.md index 8a4a24b..2c32d46 100644 --- a/README.md +++ b/README.md @@ -1,116 +1,99 @@ -# 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 +$ npx memory-viz --output demo_output.svg demo.json ``` -where `` 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 @@ -118,16 +101,4 @@ 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). diff --git a/demo/README.md b/demo/README.md new file mode 100644 index 0000000..5190a6f --- /dev/null +++ b/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`. diff --git a/docs/README.md b/docs/README.md index cdf0733..5bb0dc3 100644 --- a/docs/README.md +++ b/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= npm run deploy ``` diff --git a/examples/memory-viz-api/demo.js b/examples/memory-viz-api/demo.js new file mode 100644 index 0000000..c5a132e --- /dev/null +++ b/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"); diff --git a/examples/memory-viz-api/demo_output.svg b/examples/memory-viz-api/demo_output.svg new file mode 100644 index 0000000..d9ec393 --- /dev/null +++ b/examples/memory-viz-api/demo_output.svg @@ -0,0 +1,33 @@ +lst1id82lst2id84pid99did10tid11__main__"David is cool!"id19str7id13int \ No newline at end of file diff --git a/examples/memory-viz-browser/index.html b/examples/memory-viz-browser/index.html new file mode 100644 index 0000000..027f2a7 --- /dev/null +++ b/examples/memory-viz-browser/index.html @@ -0,0 +1,47 @@ + + + + + MemoryViz in the Browser! + + + + + + + +

A minimal example of MemoryViz in the browser

+
+ +
+ + diff --git a/examples/memory-viz-cli/README.md b/examples/memory-viz-cli/README.md new file mode 100644 index 0000000..570e9dd --- /dev/null +++ b/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`. diff --git a/examples/memory-viz-cli/demo.json b/examples/memory-viz-cli/demo.json new file mode 100644 index 0000000..61cc2a3 --- /dev/null +++ b/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 + } +] diff --git a/examples/memory-viz-cli/demo_output.svg b/examples/memory-viz-cli/demo_output.svg new file mode 100644 index 0000000..ab77bff --- /dev/null +++ b/examples/memory-viz-cli/demo_output.svg @@ -0,0 +1,33 @@ +lst1id82lst2id84pid99did10tid11__main__"David is cool!"id19str7id13int \ No newline at end of file diff --git a/memory-viz/README.md b/memory-viz/README.md index 5acfd27..1e5f0f5 100644 --- a/memory-viz/README.md +++ b/memory-viz/README.md @@ -1,22 +1,62 @@ # MemoryViz: Creating memory model diagrams -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. +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 - ``` +```console +$ npm install memory-viz +``` + +## Usage + +MemoryViz can be run from the command line or using its Javascript API. + +### Command-line interface + +Given a JSON file [`demo.json`](examples/demo.json) that encodes a state of Python memory and some styling options: + +```json +[ + { + "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 + } +] +``` + +you can run the following command in the terminal: + +```console +$ npx memory-viz --output demo_output.svg demo.json +``` + +This producs an SVG file, `demo_output.svg`, that visualizes the state of memory: + +![Sample usage svg output](examples/demo_output.svg) -## Sample usage +## Javascript API (Node.js) -Running the following file: +Call the `draw` function on an array that encodes a state of Python memory and some styling options. +Here's a complete example, which produces the same SVG output as above. ```js const { draw } = require("memory-viz"); @@ -41,62 +81,55 @@ const objects = [ }, ]; -const m = draw(objects, true, { width: 1300 }); +const model = draw(objects, true, { width: 1300 }); -m.save("simple_demo.svg"); +model.save("demo_output.svg"); ``` -produces a file `simple_demo.svg` that looks like the following: +### Javascript API (browser) -![Sample usage svg output](../docs/docs/99-api/examples/simple_demo/simple_demo.svg) +MemoryViz can also be run in the browser by loading the library from a CDN (e.g., [jsDelivr](https://cdn.jsdelivr.net/npm/memory-viz@latest/dist/memory-viz.bundle.js)) and accessing the global `memoryViz` object. +Here is a [standalone example](https://github.com/david-yz-liu/memory-viz/tree/master/examples/memory-viz-browser/index.html). -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/). +## Contributing -### MemoryViz CLI - -To use the MemoryViz CLI, run: - -```console -$ npx memory-viz -``` - -where `` 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. - -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. +### Installation -_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. +1. Install [Node.js](https://nodejs.org/en/). +2. Clone the MemoryViz repository and `cd` into it: -For more information, check out the project [documentation website](https://www.cs.toronto.edu/~david/memory-viz/docs/cli). + ```console + $ git clone https://github.com/david-yz-liu/memory-viz.git + $ cd memory-viz + ``` -## Developers +3. Install the dependencies: -### Installation + ```console + $ npm install + ``` -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: +4. Install the pre-commit hooks to automatically format your code when you make commits: ```console - $ npm install + $ npx husky init ``` -4. Compile the Javascript assets using [webpack](https://webpack.js.org/guides/getting-started/): +5. Compile the MemoryViz library: ```console $ npm run build-dev --workspace=memory-viz ``` -5. Install the pre-commit hooks to automatically format your code when you make commits: +6. Run the test suite to check that all tests pass: ```console - $ npx husky install - $ npm pkg set scripts.prepare="husky install" - $ npx husky add .husky/pre-commit "npx lint-staged" + $ npm test ``` -### Automatic Javascript compilation +### Developer tips -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: +**Automatic Javascript compilation**. 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 @@ -106,14 +139,4 @@ This will use `webpack` to watch for changes to the Javascript source files and _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 - -To run the test suite, execute the following command: - -```console -$ npm run test --workspace=memory-viz -``` - -#### Viewing Jest SVG snapshots - -To easily view the Jest SVG snapshots, open the file `memory-viz/src/tests/__snapshots__/snapshot.html` and select the snapshot outputs with the `*.snap` extension. +**Viewing Jest SVG snapshots.** To easily view the Jest SVG snapshots, open the file `memory-viz/src/tests/__snapshots__/snapshot.html` and select the snapshot outputs with the `*.snap` extension. diff --git a/webstepper/CHANGELOG.md b/webstepper/CHANGELOG.md index c9db1ce..0d7a6f6 100755 --- a/webstepper/CHANGELOG.md +++ b/webstepper/CHANGELOG.md @@ -16,6 +16,10 @@ and adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ### 🚨 Breaking changes +### 📚 Documentation changes + +- Added a README. + ### 🔧 Internal changes - Added a script for installing the Webstepper build to a specified path. diff --git a/webstepper/README.md b/webstepper/README.md new file mode 100644 index 0000000..7731250 --- /dev/null +++ b/webstepper/README.md @@ -0,0 +1,23 @@ +# MemoryViz Webstepper Website + +This folder contains the source code for the `memory-viz-webstepper` project. + +## Developers + +To run the demo website locally, follow these instructions from the `memory-viz/webstepper/` folder. + +_Note_: you can instead run the commands in the root project directory by adding the argument `--workspace=webstepper`. + +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`. diff --git a/webstepper/package.json b/webstepper/package.json index ff29c63..e93cdc8 100644 --- a/webstepper/package.json +++ b/webstepper/package.json @@ -15,6 +15,10 @@ "url": "git+https://github.com/david-yz-liu/memory-viz.git" }, "author": "David Liu", + "contributors": [ + "Yoonie Jang", + "Siqi (Leo) Liu" + ], "license": "MIT", "bugs": { "url": "https://github.com/david-yz-liu/memory-viz/issues"