Feature: Adding better docs to the application

.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/*

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"

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)

docs/src/components/accounts.md

@@ -0,0 +1,3 @@
+# Accounts
+
+## coming soon

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

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.
+

docs/src/components/parties.md

@@ -0,0 +1,3 @@
+# Parties
+
+## coming soon

docs/src/components/transactions.md

@@ -0,0 +1,4 @@
+# Transactions
+
+
+## coming soon

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

docs/src/interface/login.md

@@ -0,0 +1 @@
+# login

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. 
+

docs/src/interface/manage_accounts.md

@@ -0,0 +1 @@
+# manage accounts

docs/src/interface/manage_parties.md

@@ -0,0 +1 @@
+# manage parties

docs/src/interface/manage_transactions.md

@@ -0,0 +1 @@
+# manage transactions

docs/src/interface/mission_control.md

@@ -0,0 +1 @@
+# mission control

docs/src/misc.md

@@ -0,0 +1,3 @@
+# Final Notes
+
+tbc

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. 
+

docs/src/reports/future.md

@@ -0,0 +1 @@
+# future forecasting

docs/src/reports/historical.md

@@ -0,0 +1 @@
+# historical reporting

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.

docs/src/reports/simulation.md

@@ -0,0 +1 @@
+# hypothetical simulations

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)"

front/templates/base.html

@@ -22,6 +22,7 @@
 
     <body>
         <a href="{{ url_for('home.home_page') }}" class="button"> Home </a>
+	<a href="{{ url_for('home.stop_server') }}" class="button"> Shutdown Server </a>
         {% with messages = get_flashed_messages(with_categories=true) %} {% if
         messages %} {% for category, message in messages %}
         <div

front/templates/home.html

@@ -2,6 +2,12 @@
 {% block title %} Home {% endblock %}
 {% block content %}
 <h1>Home of Verity</h1>
+<div>
+	<h2>link to user docs and user guide</h2>
+<button onclick="window.location.href='http://localhost:3000';">
+      		Docs and User Guide
+	</button>
+</div>
 <div>
     <form action="{{url_for('home.submit_user_name')}}" method="POST">
         <p>Create New User:</p>

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