From a8f80a02b88055cfcb45664ce3a3d24c2b2da98c Mon Sep 17 00:00:00 2001 From: Terry Truong Date: Sun, 10 Jul 2022 23:41:20 +1000 Subject: Update project-level and client-side documentation --- LICENCE.txt | 19 +++++++++ LICENSE.txt | 19 --------- README.md | 83 ++++++++++++++++++++++++++++++---------- backend/README.md | 4 +- backend/data/README.md | 2 +- package.json | 12 +++--- src/App.vue | 6 +-- src/README.md | 41 ++++++++++---------- src/components/AncestryBar.vue | 2 +- src/components/HelpModal.vue | 4 +- src/components/LoadingModal.vue | 4 +- src/components/SButton.vue | 3 +- src/components/SearchModal.vue | 4 +- src/components/SettingsModal.vue | 4 +- src/components/Tile.vue | 3 +- src/components/TileInfoModal.vue | 3 +- src/components/TutorialPane.vue | 8 ++-- src/index.css | 46 +++++++++++----------- src/lib.ts | 4 +- src/main.ts | 8 ++-- src/tol.ts | 6 +-- 21 files changed, 163 insertions(+), 122 deletions(-) create mode 100644 LICENCE.txt delete mode 100644 LICENSE.txt diff --git a/LICENCE.txt b/LICENCE.txt new file mode 100644 index 0000000..47844fb --- /dev/null +++ b/LICENCE.txt @@ -0,0 +1,19 @@ +Copyright 2022 Terry Truong + +Permission is hereby granted, free of charge, to any person obtaining a +copy of this software and associated documentation files (the "Software"), +to deal in the Software without restriction, including without limitation +the rights to use, copy, modify, merge, publish, distribute, sublicense, +and/or sell copies of the Software, and to permit persons to whom the +Software is furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included +in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL +THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR +OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, +ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +OTHER DEALINGS IN THE SOFTWARE. diff --git a/LICENSE.txt b/LICENSE.txt deleted file mode 100644 index 47844fb..0000000 --- a/LICENSE.txt +++ /dev/null @@ -1,19 +0,0 @@ -Copyright 2022 Terry Truong - -Permission is hereby granted, free of charge, to any person obtaining a -copy of this software and associated documentation files (the "Software"), -to deal in the Software without restriction, including without limitation -the rights to use, copy, modify, merge, publish, distribute, sublicense, -and/or sell copies of the Software, and to permit persons to whom the -Software is furnished to do so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included -in all copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL -THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR -OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, -ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR -OTHER DEALINGS IN THE SOFTWARE. diff --git a/README.md b/README.md index e354e7e..a283d6a 100644 --- a/README.md +++ b/README.md @@ -1,27 +1,70 @@ # Tilo -Provides an interactive visualisation of the biological Tree of Life. + +A visual explorer for the biological Tree of Life. + +## Project Overview + +The UI is largely coded in Typescript, using the [Vue](https://vuejs.org) +framework, with [Vite](https://vitejs.dev) as the build tool. Much of +the styling is done using [Tailwind](https://tailwindcss.com). Packages +are managed using [npm](https://www.npmjs.com) and [Node.js](https://nodejs.org). + +On the server side, tree data is served and generated using Python, with packages +managed using [Pip](https://pypi.org/project/pip). Tree data is stored using [Sqlite](https://www.sqlite.org). ## Files -- package.json: Contains project information, including package dependencies. -- src: Contains most of the client-side code. -- index.html: Holds code for the main page, into which code from 'src' will be included. -- backend: Contains code for the server, and generating tree-of-life data -- vite.config.js: For configuring Vite. -- tailwind.config.js: For configuring Tailwind. -- postcss.config.js: For configuring Tailwind. -- tsconfig.json: For configuring Typescript. -- .gitignore: Lists files to be ignored by Git. -- public: Contains files to be copied unchanged when building for production. - -## Overview -(TODO) + +### Project Level +- **package.json**: Contains npm project information, such as package dependencies. +- **package-lock.json**: Auto-generated by npm. Used for replicable installations. +- **LICENCE.txt**: This project's license (MIT). +- **.gitignore**: Lists files to be ignored by Git. +### Client & Server +- **src**: Contains most of the client-side code. +- **index.html**: Holds code for the main page, into which code from 'src' will be included. +- **public**: Contains files to be copied unchanged in the production-build of the UI. +- **backend**: Contains code for the server, and for generating tree-of-life data. +### Configuration +- **vite.config.js**: For configuring Vite. +- **tailwind.config.js**: For configuring Tailwind. +- **postcss.config.js**: For configuring Tailwind. +- **tsconfig.json**: For configuring Typescript. ## Setup Instructions -(TODO) -## +Note: Running your own version of the client and server should be +straightforward, but generating the database will take a long time. +More details are in backend/data/README.md. + +### Base Requirements +- **[Python](https://www.python.org/downloads)**: For running server-side code, and generating the database. +- **Pip**: For installing Python packages. Included in the Python download. +- **[Git](https://git-scm.com/downloads)** (optional): For downloading and viewing snapshots of the project. + +### Client Side +1. If you don't have npm or Node.js installed, you can download a Node installer from + , which includes npm. This project was coded using version 16. +1. In this directory, run the command `npm install`, which install packages listed in + package.json, creating a `node_modules` directory to hold them. + +### Server Side +1. If you don't have Python 3 installed, see . + The package manager Pip is included. +1. The database used by the server is generated using scripts in backend/data/. + See it's README.md for instructions. You'll likely need to install a few + packages using Pip. +1. To run the dev server, you'll need to install jsonpickle. This can be done + using `python -m pip install jsonpickle`. If you want to keep the installed + package separate from your system's packages, it's common practice to use + the 'venv' module. + +### Running Tilo +1. In the backend/ directory, run `./server.py`, which starts a basic HTTP server that provides + tree-of-life data on port 8000. +1. In this directory, or somewhere in src/, run `npm run dev`. This starts a dev server that + provides Tilo's user interface on port 3000. +1. Open a web browser, and navigate to . + +## Licence -During development, a client request to the server on the same machine -would be blocked due to the Same Origin Policy. This is avoided by -adding an 'Access-Control-Allow-Origin: *' header to server responses. -This should be disabled during production. +Tilo is licensed under the MIT licence, provided in LICENSE.txt diff --git a/backend/README.md b/backend/README.md index 358ed72..1823576 100644 --- a/backend/README.md +++ b/backend/README.md @@ -1,7 +1,7 @@ # Files +- data: Contains scripts for generating the tree-of-life database +- tilo.py: WSGI script that serves tree-of-life data - server.py: Basic dev server that serves a WSGI script -- tilo.py: WSGI script that serves tree-of-life data -- data: Contains scripts for generating the tree-of-life database # During development Having generated the database as data/data.db, running `server.py`, diff --git a/backend/data/README.md b/backend/data/README.md index 13aeb89..ba64114 100644 --- a/backend/data/README.md +++ b/backend/data/README.md @@ -49,7 +49,7 @@ This directory holds files used to generate data.db, which contains tree-of-life For the most part, these steps should be done in order. As a warning, the whole process takes a lot of time and file space. The tree will probably -have about 2.5 billion nodes. Downloading the images will take several days, and occupy over +have about 2.5 billion nodes. Downloading the images takes several days, and occupies over 200 GB. And if you want good data, you'll need to do some manual review, which can take weeks. ## Environment diff --git a/package.json b/package.json index f9c23ff..f20f11e 100644 --- a/package.json +++ b/package.json @@ -1,8 +1,8 @@ { - "name": "grid-of-life", + "name": "tilo", "private": true, "version": "0.0.0", - "description": "An interactive visualisation of the biological tree of life", + "description": "A visual explorer for the biological Tree of Life", "scripts": { "dev": "vite", "build": "vue-tsc --noEmit && vite build", @@ -12,16 +12,16 @@ "author": "Terry Truong", "license": "MIT", "dependencies": { - "smartcrop-cli": "^2.0.3", - "vue": "^3.2.25" + "vue": "^3.2.25", + "smartcrop-cli": "^2.0.3" }, "devDependencies": { + "vite": "^2.8.0", "@vitejs/plugin-vue": "^2.2.0", + "tailwindcss": "^3.0.23", "autoprefixer": "^10.4.2", "postcss": "^8.4.7", - "tailwindcss": "^3.0.23", "typescript": "^4.6.2", - "vite": "^2.8.0", "vue-tsc": "^0.32.1" } } diff --git a/src/App.vue b/src/App.vue index f26e1fb..4285f6a 100644 --- a/src/App.vue +++ b/src/App.vue @@ -101,6 +101,9 @@ import {queryServer, InfoResponse, Action, UiOptions, getDefaultLytOpts, getDefaultUiOpts, OptionType} from './lib'; import {arraySum, randWeightedChoice, timeout} from './util'; +// Constants +const SERVER_WAIT_MSG = 'Loading data'; +const PROCESSING_WAIT_MSG = 'Processing'; // Type representing auto-mode actions type AutoAction = 'move across' | 'move down' | 'move up' | Action; // Function used in auto-mode to reduce action cycles @@ -117,9 +120,6 @@ function getReverseAction(action: AutoAction): AutoAction | null { return null; } } -// Constants -const SERVER_WAIT_MSG = 'Loading data'; -const PROCESSING_WAIT_MSG = 'Processing'; export default defineComponent({ data(){ diff --git a/src/README.md b/src/README.md index 23f05ee..5c88b2e 100644 --- a/src/README.md +++ b/src/README.md @@ -1,21 +1,22 @@ # Files -- main.ts: Included by ../index.html. Creates the main Vue component. -- App.vue: The main Vue component. -- components: - - Tile.vue: Displays a tree-of-life node. - - TileInfoModal.vue: Modal displaying info about a Tile's node. - - SearchModal.vue: Modal providing a search bar. - - SettingsModal: Modal displaying configurable settings. - - HelpModal.vue: Modal displaying help info. - - AncestryBar.vue: Displays ancestors of the outermost Tile. - - TutorialPane.vue: Displays tutorial content. - - LoadingModal.vue: Displays a loading indicator. - - SButton.vue: Simple button component. - - IconButton.vue: Simple button component containing an SVG icon. - - SCollapsible.vue: Simple collapsible-content component. - - icon: Contains components that display SVG icons. -- lib.ts: Contains classes/types and utility functions. -- layout.ts: Contains code for laying out Tiles. -- util.ts: Contains utility functions. -- index.css: Included by main.ts. Provides Tailwind's CSS classes. -- env.d.ts: From Vite's template files. +- **main.ts**: Included by ../index.html. Creates the main Vue component. +- **App.vue**: The main Vue component. +- **components**: + - **Tile.vue**: Displays a tree-of-life node. + - **TileInfoModal.vue**: Modal displaying info about a Tile's node. + - **SearchModal.vue**: Modal providing a search bar. + - **SettingsModal**: Modal displaying configurable settings. + - **HelpModal.vue**: Modal displaying help info. + - **AncestryBar.vue**: Displays ancestors of the outermost Tile. + - **TutorialPane.vue**: Displays tutorial content. + - **LoadingModal.vue**: Displays a loading indicator. + - **SButton.vue**: Simple button component. + - **IconButton.vue**: Simple button component containing an SVG icon. + - **SCollapsible.vue**: Simple collapsible-content component. + - **icon**: Contains components that display SVG icons. +- **tol.ts**: Holds types for tree-of-life data. +- **layout.ts**: Holds code for laying out tiles. +- **lib.ts**: Holds project-wide globals. +- **util.ts**: Holds utility functions. +- **index.css**: Included by main.ts. Provides Tailwind's CSS classes. +- **env.d.ts**: From Vite's template files. diff --git a/src/components/AncestryBar.vue b/src/components/AncestryBar.vue index fcf9933..6f2d37c 100644 --- a/src/components/AncestryBar.vue +++ b/src/components/AncestryBar.vue @@ -75,7 +75,7 @@ export default defineComponent({ }, }, watch: { - // Used to scroll to end of bar upon node/screen changes + // For scrolling-to-end upon node/screen changes nodes(){ this.$nextTick(() => this.scrollToEnd()); }, diff --git a/src/components/HelpModal.vue b/src/components/HelpModal.vue index 7375584..cc11afb 100644 --- a/src/components/HelpModal.vue +++ b/src/components/HelpModal.vue @@ -358,14 +358,14 @@