diff --git a/.gitignore b/.gitignore index 2100a97..bfce885 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,5 @@ # verity additions -logs/ +logs/* *.db **/*.db-wal **/*.db-shm @@ -18,3 +18,6 @@ wheels/ # Virtual environments .venv + +# mdbook bits +docs/book/* diff --git a/docs/book.toml b/docs/book.toml new file mode 100644 index 0000000..c57fc5d --- /dev/null +++ b/docs/book.toml @@ -0,0 +1,10 @@ +[book] +authors = ["Jake Pullen"] +language = "en" +src = "src" +title = "Verity User Guide" + +[output] + +[output.html] +git-repository-url="https://github.com/Jake-Pullen/verity" diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md new file mode 100644 index 0000000..cc49093 --- /dev/null +++ b/docs/src/SUMMARY.md @@ -0,0 +1,26 @@ +# Summary + +[Home](./readme.md) + +--- + +- [The Components](./components/main.md) + - [Users](./components/users.md) + - [Categories](./components/categories.md) + - [Accounts](./components/accounts.md) + - [Parties](./components/parties.md) + - [Transactions](./components/transactions.md) +- [The Interface](./interface/main.md) + - [login](./interface/login.md) + - [mission control](./interface/mission_control.md) + - [manage accounts](./interface/manage_accounts.md) + - [manage parties](./interface/manage_parties.md) + - [manage transactions](./interface/manage_transactions.md) +- [The Reports](./reports/main.md) + - [historical reporting](./reports/historical.md) + - [future forecasting](./reports/future.md) + - [hypothetical simulations](./reports/simulation.md) + +--- + +[Final Notes](./misc.md) diff --git a/docs/src/components/accounts.md b/docs/src/components/accounts.md new file mode 100644 index 0000000..9dea6d7 --- /dev/null +++ b/docs/src/components/accounts.md @@ -0,0 +1,3 @@ +# Accounts + +## coming soon diff --git a/docs/src/components/categories.md b/docs/src/components/categories.md new file mode 100644 index 0000000..a7ba9a2 --- /dev/null +++ b/docs/src/components/categories.md @@ -0,0 +1,52 @@ +# Categories + +The Category is the logical account for money storage and transfer. +The Category is a hierarchy of 3 tiers (our logical limit, in theory we could have infinite tiers) + +The Category class has the following attributes: + +- database (Database Object) + * The database object, passed in so we can run tests with a theoretical database. + +- name (String) + * the name of the category + +- budget_value (int) + * The logical value of stored money (see [Transactions](./transactions.md) for why we chose int over float or double) + * (NOT YET IMPLEMENTED) if this is a parent category, Should be a summed value of all child budget_values + +- id (int) + * The ID of the category as stored in the database + +- children (List of Category Objects) + * used to manage the child categories. + +- parent (Category Object) + * used to manage the Parent Category + +- user_id (int) + * the ID of the user as stored in the database + +The Category class has the following methods: + +- add + * Adds the category to the database + * Returns category id (INT) if successful + +- get_default_category + * Sets the parent category to the internal master category of the user. + * does not return + +- get_id + * sets the id attribute of the category (or 0 if failed) + +- get_name + * sets the name attribute of the category (or 'unknown' if failed) + +- get_children + * Gets from the database all children of the category, + * for each child, creates a Category object and adds that object to the children attribute. + +- get + * Gets the information of a category from the database + * returns the database resuults diff --git a/docs/src/components/main.md b/docs/src/components/main.md new file mode 100644 index 0000000..1d68819 --- /dev/null +++ b/docs/src/components/main.md @@ -0,0 +1,9 @@ +# The Components + +These are the technical areas of the code, describing their general area of use. + +Each component is a class in the code base (and sometimes child classes). +While the codebase aim is to be written as clearly and cleanly as possible, following good practice +in naming conventions and doc strings. We should be writing documentation here so that it is accessible +via the web when Verity is running. + diff --git a/docs/src/components/parties.md b/docs/src/components/parties.md new file mode 100644 index 0000000..779d7c9 --- /dev/null +++ b/docs/src/components/parties.md @@ -0,0 +1,3 @@ +# Parties + +## coming soon diff --git a/docs/src/components/transactions.md b/docs/src/components/transactions.md new file mode 100644 index 0000000..4cca9ed --- /dev/null +++ b/docs/src/components/transactions.md @@ -0,0 +1,4 @@ +# Transactions + + +## coming soon diff --git a/docs/src/components/users.md b/docs/src/components/users.md new file mode 100644 index 0000000..ea9d743 --- /dev/null +++ b/docs/src/components/users.md @@ -0,0 +1,55 @@ +# Users + +The User as expected is the "user" of Verity, so if wanted / needed multiple users could be set up. +The User is a logical container of all information in Verity. Meaning a user owns all other components. + + +NOTE: The users are currently not password protected, so only set up & share this with users you trust. +But also, hypothetical users could be made for various purposes, testing / demonstrating. + +Each user is completely separate from one another, so adding a category / account / transaction to +one user, will only stay on that user and not be added to another. + +The User class is initialised when logging in or creating a new user in the front end. +The User class has the following attributes: + +- database (Database Object) + * the database object is passed in so we can run tests with a theoretical database. + +- name (string) + * the name of the user as stored in the database + +- id (int) + * The id of the user as stored in the database + +- categories (List of Category Objects) + * The top level categories owned by the user. + +- internal_category_id (int) + * the internal category id for the user. + +The User class has the following methods: + +- add + * adds the user to the database + * During adding the user we add a default master category for the user +(Every transaction needs a category, so we need a master category for things like starting balance) + * returns the user id (INT) or 0 if failed + +- exists + * Checks to see if the user name already exists in the database (name not id) + * + +- get_categories + * gets all top level categories (see [Categories](./categories.md) for more info) + * returns a list of category objects + * + +- get + * loads the user into the class from the database + * does not return anything + * + +- get_internal_master_category + * loads the default master category id into the user class + * does not return anything diff --git a/docs/src/interface/login.md b/docs/src/interface/login.md new file mode 100644 index 0000000..49475fd --- /dev/null +++ b/docs/src/interface/login.md @@ -0,0 +1 @@ +# login diff --git a/docs/src/interface/main.md b/docs/src/interface/main.md new file mode 100644 index 0000000..d7d92c4 --- /dev/null +++ b/docs/src/interface/main.md @@ -0,0 +1,7 @@ +# The Interface + +## This section will cover the technical details about the front end aspect. + +Currently this is all handled on one page but will soon branch out to multiple pages +depending on what you are doing. + diff --git a/docs/src/interface/manage_accounts.md b/docs/src/interface/manage_accounts.md new file mode 100644 index 0000000..810bebe --- /dev/null +++ b/docs/src/interface/manage_accounts.md @@ -0,0 +1 @@ +# manage accounts diff --git a/docs/src/interface/manage_parties.md b/docs/src/interface/manage_parties.md new file mode 100644 index 0000000..6794674 --- /dev/null +++ b/docs/src/interface/manage_parties.md @@ -0,0 +1 @@ +# manage parties diff --git a/docs/src/interface/manage_transactions.md b/docs/src/interface/manage_transactions.md new file mode 100644 index 0000000..e65cee6 --- /dev/null +++ b/docs/src/interface/manage_transactions.md @@ -0,0 +1 @@ +# manage transactions diff --git a/docs/src/interface/mission_control.md b/docs/src/interface/mission_control.md new file mode 100644 index 0000000..a668c68 --- /dev/null +++ b/docs/src/interface/mission_control.md @@ -0,0 +1 @@ +# mission control diff --git a/docs/src/misc.md b/docs/src/misc.md new file mode 100644 index 0000000..d63a8a7 --- /dev/null +++ b/docs/src/misc.md @@ -0,0 +1,3 @@ +# Final Notes + +tbc diff --git a/docs/src/readme.md b/docs/src/readme.md new file mode 100644 index 0000000..365409e --- /dev/null +++ b/docs/src/readme.md @@ -0,0 +1,8 @@ +# Home + +## These docs are a work in progress and will be updated as we go. + +## [Link back to Verity](localhost:5000) i think + +On the left is a breakdown of the subjects of documentation. + diff --git a/docs/src/reports/future.md b/docs/src/reports/future.md new file mode 100644 index 0000000..a71de9d --- /dev/null +++ b/docs/src/reports/future.md @@ -0,0 +1 @@ +# future forecasting diff --git a/docs/src/reports/historical.md b/docs/src/reports/historical.md new file mode 100644 index 0000000..ec01c2d --- /dev/null +++ b/docs/src/reports/historical.md @@ -0,0 +1 @@ +# historical reporting diff --git a/docs/src/reports/main.md b/docs/src/reports/main.md new file mode 100644 index 0000000..c1eded2 --- /dev/null +++ b/docs/src/reports/main.md @@ -0,0 +1,10 @@ +# The Reports + +The Preorts has not been built yet, but the plan is to have 3 separate categories of reporting. + +1. Historical reports + * This will contain visuals on your historic spending, allowing you to see insights. +1. Future Forecasting + * This will take your historical data and try to predict what a possible future could look like +1. Simulation predictions + * This will be your what if scenarios, running simulations and giving the results based on sets of data and your historical data. diff --git a/docs/src/reports/simulation.md b/docs/src/reports/simulation.md new file mode 100644 index 0000000..04a0b33 --- /dev/null +++ b/docs/src/reports/simulation.md @@ -0,0 +1 @@ +# hypothetical simulations diff --git a/front/home.py b/front/home.py index b5a0690..c5077ae 100644 --- a/front/home.py +++ b/front/home.py @@ -1,4 +1,6 @@ import logging +import os +import subprocess from flask import Blueprint, flash, redirect, render_template, request, session, url_for @@ -156,3 +158,22 @@ def submit_category(): else: flash("Category saved!", "success") return redirect(url_for("home.home_page")) + + +def stop_mdbook(): + try: + process = subprocess.run(["pgrep", "mdbook"], capture_output=True) + # process.kill() + pid = process.stdout.strip() + print(f"aiming to kill pid: {pid}") + os.kill(int(pid), 9) + logger.info(f"mdbook process stopped with PID: {pid}") + except Exception as e: + print(f"Error stopping mdbook: {e}") + + +@home_bp.route("/stop") +def stop_server(): + stop_mdbook() + os.kill(os.getpid(), 9) + return "Stopping servers... (check your logs)" diff --git a/front/templates/base.html b/front/templates/base.html index dffef7b..6f6473b 100644 --- a/front/templates/base.html +++ b/front/templates/base.html @@ -22,6 +22,7 @@ Home + Shutdown Server {% with messages = get_flashed_messages(with_categories=true) %} {% if messages %} {% for category, message in messages %}
Home of Verity +
+

link to user docs and user guide

+ +

Create New User:

diff --git a/start_server.sh b/start_server.sh new file mode 100755 index 0000000..2dfeff2 --- /dev/null +++ b/start_server.sh @@ -0,0 +1,6 @@ +# calls mdbooks to run in the backgroun +echo "Starting mdbook to run in the background" +mdbook serve docs & + +echo "Starting Verity" +uv run verity.py