From fc3bb23bfa7066df6461f0c01871ca312b9e0f07 Mon Sep 17 00:00:00 2001 From: Jake Pullen Date: Thu, 17 Jul 2025 10:55:56 +0100 Subject: [PATCH 1/4] =?UTF-8?q?feat:=20=E2=9C=A8=20Better=20Documentation?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .gitignore | 5 ++++- docs/book.toml | 10 +++++++++ docs/src/SUMMARY.md | 26 +++++++++++++++++++++++ docs/src/components/accounts.md | 1 + docs/src/components/categories.md | 1 + docs/src/components/main.md | 1 + docs/src/components/parties.md | 1 + docs/src/components/transactions.md | 1 + docs/src/components/users.md | 1 + docs/src/interface/login.md | 1 + docs/src/interface/main.md | 1 + docs/src/interface/manage_accounts.md | 1 + docs/src/interface/manage_parties.md | 1 + docs/src/interface/manage_transactions.md | 1 + docs/src/interface/mission_control.md | 1 + docs/src/misc.md | 1 + docs/src/readme.md | 1 + docs/src/reports/future.md | 1 + docs/src/reports/historical.md | 1 + docs/src/reports/main.md | 1 + docs/src/reports/simulation.md | 1 + front/home.py | 21 ++++++++++++++++++ front/templates/base.html | 1 + front/templates/home.html | 6 ++++++ start_server.sh | 5 +++++ 25 files changed, 91 insertions(+), 1 deletion(-) create mode 100644 docs/book.toml create mode 100644 docs/src/SUMMARY.md create mode 100644 docs/src/components/accounts.md create mode 100644 docs/src/components/categories.md create mode 100644 docs/src/components/main.md create mode 100644 docs/src/components/parties.md create mode 100644 docs/src/components/transactions.md create mode 100644 docs/src/components/users.md create mode 100644 docs/src/interface/login.md create mode 100644 docs/src/interface/main.md create mode 100644 docs/src/interface/manage_accounts.md create mode 100644 docs/src/interface/manage_parties.md create mode 100644 docs/src/interface/manage_transactions.md create mode 100644 docs/src/interface/mission_control.md create mode 100644 docs/src/misc.md create mode 100644 docs/src/readme.md create mode 100644 docs/src/reports/future.md create mode 100644 docs/src/reports/historical.md create mode 100644 docs/src/reports/main.md create mode 100644 docs/src/reports/simulation.md create mode 100755 start_server.sh 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..5b6def5 --- /dev/null +++ b/docs/src/components/accounts.md @@ -0,0 +1 @@ +# Accounts diff --git a/docs/src/components/categories.md b/docs/src/components/categories.md new file mode 100644 index 0000000..bdd16ff --- /dev/null +++ b/docs/src/components/categories.md @@ -0,0 +1 @@ +# Categories diff --git a/docs/src/components/main.md b/docs/src/components/main.md new file mode 100644 index 0000000..dc6f657 --- /dev/null +++ b/docs/src/components/main.md @@ -0,0 +1 @@ +# The Components diff --git a/docs/src/components/parties.md b/docs/src/components/parties.md new file mode 100644 index 0000000..de47949 --- /dev/null +++ b/docs/src/components/parties.md @@ -0,0 +1 @@ +# Parties diff --git a/docs/src/components/transactions.md b/docs/src/components/transactions.md new file mode 100644 index 0000000..a5fd09c --- /dev/null +++ b/docs/src/components/transactions.md @@ -0,0 +1 @@ +# Transactions diff --git a/docs/src/components/users.md b/docs/src/components/users.md new file mode 100644 index 0000000..76e7c23 --- /dev/null +++ b/docs/src/components/users.md @@ -0,0 +1 @@ +# Users 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..72559f7 --- /dev/null +++ b/docs/src/interface/main.md @@ -0,0 +1 @@ +# The Interface 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..aeec844 --- /dev/null +++ b/docs/src/misc.md @@ -0,0 +1 @@ +# Final Notes diff --git a/docs/src/readme.md b/docs/src/readme.md new file mode 100644 index 0000000..291ca38 --- /dev/null +++ b/docs/src/readme.md @@ -0,0 +1 @@ +# Home 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..3f624c8 --- /dev/null +++ b/docs/src/reports/main.md @@ -0,0 +1 @@ +# The Reports 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..f7d9b25 100644 --- a/front/home.py +++ b/front/home.py @@ -1,4 +1,6 @@ import logging +import subprocess +import os 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..0549603 --- /dev/null +++ b/start_server.sh @@ -0,0 +1,5 @@ +# calls mdbooks to run in the backgroun +# +mdbook serve docs & + +uv run verity.py From e34262e4061fbe13c7909d7d5b87e98b1c7bec7b Mon Sep 17 00:00:00 2001 From: Jake Pullen Date: Thu, 17 Jul 2025 11:16:13 +0100 Subject: [PATCH 2/4] test sign --- start_server.sh | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/start_server.sh b/start_server.sh index 0549603..2dfeff2 100755 --- a/start_server.sh +++ b/start_server.sh @@ -1,5 +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 From af42046be968a2f9e580b1562b353a9ba9fcaba4 Mon Sep 17 00:00:00 2001 From: Jake Pullen Date: Thu, 17 Jul 2025 13:43:57 +0100 Subject: [PATCH 3/4] =?UTF-8?q?docs:=20=F0=9F=93=9C=20Added=20the=20curren?= =?UTF-8?q?t=20documentation.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/src/components/accounts.md | 2 ++ docs/src/components/categories.md | 51 +++++++++++++++++++++++++++ docs/src/components/main.md | 8 +++++ docs/src/components/parties.md | 2 ++ docs/src/components/transactions.md | 3 ++ docs/src/components/users.md | 54 +++++++++++++++++++++++++++++ docs/src/interface/main.md | 6 ++++ docs/src/misc.md | 2 ++ docs/src/readme.md | 7 ++++ docs/src/reports/main.md | 9 +++++ 10 files changed, 144 insertions(+) diff --git a/docs/src/components/accounts.md b/docs/src/components/accounts.md index 5b6def5..9dea6d7 100644 --- a/docs/src/components/accounts.md +++ b/docs/src/components/accounts.md @@ -1 +1,3 @@ # Accounts + +## coming soon diff --git a/docs/src/components/categories.md b/docs/src/components/categories.md index bdd16ff..a7ba9a2 100644 --- a/docs/src/components/categories.md +++ b/docs/src/components/categories.md @@ -1 +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 index dc6f657..1d68819 100644 --- a/docs/src/components/main.md +++ b/docs/src/components/main.md @@ -1 +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 index de47949..779d7c9 100644 --- a/docs/src/components/parties.md +++ b/docs/src/components/parties.md @@ -1 +1,3 @@ # Parties + +## coming soon diff --git a/docs/src/components/transactions.md b/docs/src/components/transactions.md index a5fd09c..4cca9ed 100644 --- a/docs/src/components/transactions.md +++ b/docs/src/components/transactions.md @@ -1 +1,4 @@ # Transactions + + +## coming soon diff --git a/docs/src/components/users.md b/docs/src/components/users.md index 76e7c23..ea9d743 100644 --- a/docs/src/components/users.md +++ b/docs/src/components/users.md @@ -1 +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/main.md b/docs/src/interface/main.md index 72559f7..d7d92c4 100644 --- a/docs/src/interface/main.md +++ b/docs/src/interface/main.md @@ -1 +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/misc.md b/docs/src/misc.md index aeec844..d63a8a7 100644 --- a/docs/src/misc.md +++ b/docs/src/misc.md @@ -1 +1,3 @@ # Final Notes + +tbc diff --git a/docs/src/readme.md b/docs/src/readme.md index 291ca38..365409e 100644 --- a/docs/src/readme.md +++ b/docs/src/readme.md @@ -1 +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/main.md b/docs/src/reports/main.md index 3f624c8..c1eded2 100644 --- a/docs/src/reports/main.md +++ b/docs/src/reports/main.md @@ -1 +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. From b34843687d0b8661024e3e05b1ffc34cf138d8e9 Mon Sep 17 00:00:00 2001 From: Jake Pullen Date: Thu, 17 Jul 2025 13:53:01 +0100 Subject: [PATCH 4/4] =?UTF-8?q?fix:=20=F0=9F=9A=91=EF=B8=8F=20Ruff=20check?= =?UTF-8?q?=20fix?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- front/home.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/front/home.py b/front/home.py index f7d9b25..c5077ae 100644 --- a/front/home.py +++ b/front/home.py @@ -1,6 +1,6 @@ import logging -import subprocess import os +import subprocess from flask import Blueprint, flash, redirect, render_template, request, session, url_for