From f13e248f773181917ac798c28ece620400b148c8 Mon Sep 17 00:00:00 2001 From: David Liu Date: Thu, 23 May 2024 02:36:52 +0000 Subject: [PATCH] Update READMEs. (#33) - Standardize main project README and memory-viz package README - Fix example code and image. Fixes #21 - Add links to demo and docs website READMEs in main project README --- README.md | 411 ++++++------------------------------------- memory-viz/README.md | 61 +++++-- 2 files changed, 96 insertions(+), 376 deletions(-) diff --git a/README.md b/README.md index 2ac0c15c..e4125b17 100644 --- a/README.md +++ b/README.md @@ -8,88 +8,18 @@ This uses the [Rough.js](https://roughjs.com/) Javascript library to emulate the ## Installation (users) 1. Install [Node.js](https://nodejs.org/en/). -2. Install the `memory-viz` package from GitHub (it is currently not on npm): +2. Install the `memory-viz` package: ```console - $ npm install git+https://github.com/david-yz-liu/memory-viz.git -g + $ npm install memory-viz ``` - _Note_: omit the `-g` flag if you want to install the package into just the current working directory. +## Sample usage -## Installation (developers) +Running the following file: -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: - - ```console - $ npm install - ``` - -4. Compile the Javascript assets using [webpack](https://webpack.js.org/guides/getting-started/): - - ```console - $ npm run build-dev - ``` - -5. Install the pre-commit hooks to automatically format your code when you make commits: - - ```console - $ npx husky install - $ npm pkg set scripts.prepare="husky install" - $ npx husky add .husky/pre-commit "npx lint-staged" - ``` - -That's it! -You should then be able to try out the demo in the [Example usage](#example-usage) section below. - -### 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 -``` - -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. - -### Previewing the website - -We use [Docusaurus](https://docusaurus.io/) to generate the website from the source files under `docs/`. -To preview the website (e.g., when you make changes to the documentation): - -```console -$ cd docs -$ npm run start -``` - -## Usage - -The only function that a user will ever have to call is `user_functions.draw`. - -This function has three parameters: - -1. `objs`: The array of objects (including stack-frames) to be drawn. Each object must follow - a strict structure which is thoroughly outlined in the `object_structure.md` file. -2. `automation`: A boolean, indicating whether the location of the memory-model boxes should - be automatically generated. If this is false, the user must x and y attributes for each object - (representing the object's coordinates). -3. `configuration`: A JS object representing configuration such as the user-specified width. - Defining a `width` property is mandatory if `automation` is `true`. - -(**Note**: If the array of objects to be drawn is stored in a JSON file, the user can simply choose to pass the path to -that JSON as the first parameter to `draw`. The implementation automatically handles the case that `typeof objs === "string"`. -) - -### Simple Example - -Before showing the full capabilities of the project, here is a simple example to get you started, consisting of -one stack-frame and two objects. - -```javascript -const { draw } = require("../../dist/memory_viz.js"); +```js +const { draw } = require("memory-viz"); const objects = [ { @@ -100,13 +30,16 @@ const objects = [ stack_frame: true, }, { - isClass: false, name: "str", id: 19, value: "David is cool!", style: ["highlight"], }, - { isClass: false, name: "int", id: 13, value: 7 }, + { + name: "int", + id: 13, + value: 7, + }, ]; const m = draw(objects, true, { width: 1300 }); @@ -114,310 +47,74 @@ const m = draw(objects, true, { width: 1300 }); m.save("simple_demo.svg"); ``` -![Diagram generated for simple_demo.js file.](examples/simple_demo/simple_demo.svg) - -### Automation Example +produces a file `simple_demo.svg` that looks like the following: -One of the main capabilities offered is the automatic generation of coordinates for objects -passed by the user. +![Sample usage svg output](docs/docs/99-api/examples/simple_demo/simple_demo.svg) -```javascript -// The array version of automation.js (in automation.js same objects are used, but they are in the JSON file format.) -const { draw } = require("user_functions"); - -const objs = [ - { - isClass: true, - name: "__main__", - id: null, - value: { lst1: 82, lst2: 84, p: 99, d: 10, t: 11 }, - stack_frame: true, - }, - { - isClass: true, - name: "func", - id: null, - value: { age: 12, name: 17 }, - stack_frame: true, - }, - { - isClass: false, - name: "list", - id: 84, - value: [32, 10, 90, 57], - show_indexes: true, - }, - { isClass: false, name: "None", id: 13, value: "None" }, -]; +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/). -const configuration = { - width: 1300, - padding: 30, - top_margin: 30, - bottom_margin: 40, - left_margin: 20, - right_margin: 30, -}; +## Developers -const m = draw(objs, true, configuration); +### Installation -m.save("~/Desktop/demo.svg"); -``` - -Running node `automation_demo.js` creates a file `automation_demo.svg` that contains the following image: +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: -![Diagram generated for automation_demo.js file.](examples/automation_demo/automation_demo.svg) + ```console + $ npm install + ``` -### Manual Coordinates Example +4. Compile the Javascript assets using [webpack](https://webpack.js.org/guides/getting-started/): -Despite the automation capabilities, the user may still wish to hardcode the coordinates of the memory boxes. -To do this, they must set the `automation` parameter of the `draw` function to false (signifying that no automation -should take place), and supply `x` and `y` coordinates for _every_ object in the array (there is no notion of -"partial" automation). + ```console + $ npm run build-dev --workspace=memory-viz + ``` -Note that in the case of manual coordinates, the `configuration` parameter can provide no additional functionality, -and an empty object (`{}`) will suffice. +5. Install the pre-commit hooks to automatically format your code when you make commits: -```javascript -// The array version of automation.js (in automation.js same objects are used, but they are in the JSON file format.) -const { draw } = require("user_functions"); + ```console + $ npx husky install + $ npm pkg set scripts.prepare="husky install" + $ npx husky add .husky/pre-commit "npx lint-staged" + ``` -const objs = [ - { - isClass: true, - x: 25, - y: 200, - name: "__main__", - id: null, - value: { lst1: 82, lst2: 84, p: 99, d: 10, t: 11 }, - stack_frame: true, - }, - { - isClass: false, - x: 1050, - y: 500, - name: "dict", - id: 10, - value: { x: 81, y: 100, z: 121 }, - }, - { isClass: false, x: 1050, y: 40, name: "tuple", id: 11, value: [82, 76] }, - { isClass: false, x: 750, y: 250, name: "bool", id: 32, value: true }, -]; -const configuration = {}; +### Automatic Javascript compilation -const m = draw(objs, false, configuration); +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: -m.save("~/Desktop/manual_demo.svg"); +```console +$ npm run watch --workspace=memory-viz ``` -Running node `manual_demo.js` creates a file `manual_demo.svg` that contains the following image: - -![Diagram generated for automation_demo.js file.](examples/manual_demo/manual_demo.svg) - -### Style Features for Drawing - -The package allows user to define their own configuration for the style of the drawings. To achieve this, we utilize -rough package (see the documentation of rough package) and SVG (see the documentation of SVG for details). Rough package -is used for style configurations related to boxes (that are drawn) and SVG is mainly related to texts. -Moreover, we have created a few presets that the user can utilize (without creating custom-made style) -.We allow user to pass in a JavaScript object, as well an array (which can include a mixture of presets and user-defined styles). -Therefore, the user needs to follow the guidelines(documentation) of the aforementioned packages **and** the instructions in the `style.md` file -on how to pass these _style_ arguments. We strongly recommend the user to consult the `style.md` file. - -Also, we provide pre-sets that users can utilize. Hence, user can pass these presets (following -the instructions in the `style.md` file) - -The code for generating a memory model diagram with built-in default style will look similar to this: - -```javascript -const objs = [ - { - isClass: true, - x: 25, - y: 200, - name: "__main__", - id: null, - value: { lst1: 82, lst2: 84, p: 99, d: 10, t: 11 }, - stack_frame: true, - }, - { - isClass: false, - x: 350, - y: 350, - name: "list", - id: 54, - value: [19, 43, 28, 49], - }, - { - isClass: false, - x: 750, - y: 500, - name: "str", - id: 43, - value: "David is cool", - }, - { - isClass: false, - x: 1050, - y: 260, - name: "set", - id: 90, - value: [36, 49, 64], - }, - { - isClass: false, - x: 1050, - y: 500, - name: "dict", - id: 10, - value: { x: 81, y: 100, z: 121 }, - }, - { isClass: false, x: 750, y: 750, name: "None", id: 13, value: "None" }, -]; -``` +This will use `webpack` to watch for changes to the Javascript source files and recompile them automatically. -The produced image will be as follows: +_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. -![Diagram generated for showing our default style](examples/style_demo/nostyle_demo.svg) +### Running tests -On the other hand, the same memory model diagram can be created with utilizing styling features s follows: +To run the test suite, execute the following command: -```javascript -const objs = [ - { - isClass: true, - x: 25, - y: 200, - name: "__main__", - id: null, - value: { lst1: 82, lst2: 84, p: 99, d: 10, t: 11 }, - stack_frame: true, - style: ["highlight"], - }, - { - isClass: false, - x: 350, - y: 350, - name: "list", - id: 54, - value: [19, 43, 28, 49], - style: { text_id: { "font-style": "italic", "font-size": "x-large" } }, - }, - { - isClass: false, - x: 750, - y: 500, - name: "str", - id: 43, - value: "David is cool", - style: "highlight", - }, - { - isClass: false, - x: 1050, - y: 260, - name: "set", - id: 90, - value: [36, 49, 64], - }, - { - isClass: false, - x: 1050, - y: 500, - name: "dict", - id: 10, - value: { x: 81, y: 100, z: 121 }, - style: { text_id: { "font-style": "italic" } }, - }, - { - isClass: false, - x: 750, - y: 750, - name: "None", - id: 13, - value: "None", - style: { - text_value: { "font-style": "italic" }, - box_id: { fill: "red", fillStyle: "dots" }, - box_type: { fill: "red", fillStyle: "solid" }, - box_container: { fill: "black", fillStyle: "solid" }, - }, - }, -]; +```console +$ npm run test --workspace=memory-viz ``` -The resulting diagram will be like this: - -![Diagram generated for showing an styling features](examples/style_demo/style_demo.svg) - -### Blank Spaces Example - -In many cases, the user might want to have blank spaces in the memory model when in `automation === true` mode in the -`draw` function (if the user is "hard coding" coordinates, then he can easily include spaces wherever he desires). - -To define a blank box, you specify it as an object in the array (the classic array of objects) with three attributes: - -- `name: "BLANK"` -- `width: ...` (the desired width of the blank space) -- `height: ...` (the desired height of the blank space) - -All these attributes are mandatory, and any additional attributes will not have any effect whatsoever in the -rendering of the blank space. -Furthermore, note that `configuration.sort_by` should be `null`, as otherwise you cannot control where the -blank spaces will be located. - -In the below example we have added three blank spaces of varying dimensions. +### Building and running the documentation website -```javascript -const { draw } = require("../../dist/memory_models_rough.js"); +See [`docs/README.md`](docs/README.md). -const WIDTH = 1300; +### Building and running the demo website -const listOfObjs = [ - { - isClass: true, - name: "__main__", - id: null, - value: { lst1: 82, lst2: 84, p: 99, d: 10, t: 11 }, - stack_frame: true, - }, - { name: "BLANK", width: 100, height: 200, stack_frame: true }, - { - isClass: true, - name: "func", - id: null, - value: { age: 12, name: 17 }, - stack_frame: true, - }, - { isClass: false, name: "list", id: 82, value: [19, 43, 28, 49] }, - { - isClass: false, - name: "list", - id: 84, - value: [32, 10, 90, 57], - show_indexes: true, - }, - { isClass: false, name: "int", id: 19, value: 1969 }, - { name: "BLANK", width: 100, height: 200 }, - { isClass: false, name: "bool", id: 32, value: true }, - { isClass: false, name: "str", id: 43, value: "David is cool" }, - { name: "BLANK", width: 200, height: 150 }, - { isClass: false, name: "tuple", id: 11, value: [82, 76] }, -]; - -const configuration = { - width: WIDTH, - padding: 30, - right_margin: 20, - bottom_margin: 20, - sort_by: null, -}; +1. First, build the assets using Webpack: -const m = draw(listOfObjs, true, configuration); + ```console + $ npm run build-dev --workspace=memory-viz-demo + ``` -m.save("blankspaces_demo.svg"); -``` +2. Then run the website: -Running node `blankspaces_demo.js` creates a file `blankspaces_demo.svg` that contains the following image: + ```console + $ npm run start --workspace=memory-viz-demo + ``` -![Diagram generated for automation_demo.js file.](examples/blankspaces_demo/blankspaces_demo.svg) +3. Visit the website at `http://localhost:9000`. diff --git a/memory-viz/README.md b/memory-viz/README.md index 319ea0b9..6f34b6fb 100644 --- a/memory-viz/README.md +++ b/memory-viz/README.md @@ -14,7 +14,48 @@ This uses the [Rough.js](https://roughjs.com/) Javascript library to emulate the $ npm install memory-viz ``` -## Installation (developers) +## Sample usage + +Running the following file: + +```js +const { draw } = require("memory-viz"); + +const objects = [ + { + isClass: true, + name: "__main__", + id: null, + value: { lst1: 82, lst2: 84, p: 99, d: 10, t: 11 }, + stack_frame: true, + }, + { + name: "str", + id: 19, + value: "David is cool!", + style: ["highlight"], + }, + { + name: "int", + id: 13, + value: 7, + }, +]; + +const m = draw(objects, true, { width: 1300 }); + +m.save("simple_demo.svg"); +``` + +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/). + +## Developers + +### Installation 1. First, clone this repository. 2. Install [Node.js](https://nodejs.org/en/). @@ -57,21 +98,3 @@ To run the test suite, execute the following command: ```console $ npm run test --workspace=memory-viz ``` - -## Usage - -The only function that a user will ever have to call is `user_functions.draw`. - -This function has three parameters: - -1. `objs`: The array of objects (including stack-frames) to be drawn. Each object must follow - a strict structure which is thoroughly outlined in the `object_structure.md` file. -2. `automation`: A boolean, indicating whether the location of the memory-model boxes should - be automatically generated. If this is false, the user must x and y attributes for each object - (representing the object's coordinates). -3. `configuration`: A JS object representing configuration such as the user-specified width. - Defining a `width` property is mandatory if `automation` is `true`. - -(**Note**: If the array of objects to be drawn is stored in a JSON file, the user can simply choose to pass the path to -that JSON as the first parameter to `draw`. The implementation automatically handles the case that `typeof objs === "string"`. -)