Updated documentation

Author: niekvleeuwen

README.md

@@ -5,18 +5,31 @@ Tool designed to parse and extract data from the travel tracking app [Polarsteps
 1. **Data backup**: The data export does not support viewing your data in any useful way. To preserve the data (who knows if Polarsteps still exists in 20 years), the tool combines the data and generates a PDF document.
 2. **Data analysis & visualization**: The parsed data can also be leveraged for in-depth analysis, enabling users to gain insights into their travel patterns, destinations visited, duration of stays, distances traveled, and more. This opens up possibilities for statistical analysis, trend identification, and visualization of the trip data.
 
+## Detailed Usage Guide
+
+If you’re new to Python or command-line tools, I’ve created a step-by-step usage guide to help you install and run polarsteps-data-parser (no programming experience required).
+
+👉 Read the guide here: [Usage guide](https://github.com/niekvleeuwen/polarsteps-data-parser/blob/main/USAGE_GUIDE.md)
+
 ## Getting started
 
-### Installation
-To set up the project, ensure you have Python 3.11+ installed.
 
-Install from PyPI using pip:
+1. Clone the repository and navigate to the project root:
+
+```shell
+git clone https://github.com/niekvleeuwen/polarsteps-data-parser.git
+cd polarsteps-data-parser
+```
+
+2. Install dependencies using [uv](https://docs.astral.sh/uv/).
+   Make sure `uv` is installed on your system before proceeding.
+
 ```shell
-pip install polarsteps-data-parser
+uv sync
 ```
 
 ### Usage
-To get the following output, run `polarsteps-data-parser --help`.
+To get the following output, run `uv run polarsteps-data-parser --help`.
 
 ```shell
 Usage: polarsteps-data-parser [OPTIONS] INPUT_FOLDER
@@ -35,7 +48,7 @@ Options:
 For example, to load and analyse a trip with the data located in the `./data/trip1` folder and enrich the trip with comments, use the following command:
 
 ```shell
-polarsteps-data-parser ./data/trip1 --enrich-with-comments
+uv run polarsteps-data-parser ./data/trip1 --enrich-with-comments
 ```
 
 ## Disclaimer

USAGE_GUIDE.md

@@ -0,0 +1,109 @@
+# Usage guide
+Detailed step-by-step guide for non-programmers to install and use the polarsteps-data-parser program.
+
+## Step 1: Install Python
+
+The program requires Python. If you don’t have it installed:
+
+1. Go to the official Python website: https://www.python.org/downloads/
+1. Click Download Python (choose the latest version with a minium version of Python 3.11).
+1. **IMPORTANT:** When installing, make sure to check the box that says
+`Add Python to PATH` before clicking **Install Now**.
+
+Once installed, you’re ready to install the polarsteps data parser.
+
+## **Step 2: Open the Command Prompt (Terminal)**
+
+* On **Windows**
+  Press `Windows Key + R`, type `cmd`, and press **Enter**.
+
+* On **Mac**
+  Press `Command + Space`, type `Terminal`, and press **Enter**.
+
+* On **Linux**
+  Open the Terminal from your applications menu.
+
+## **Step 3: Install the Program**
+
+In the command prompt or terminal window, type this and press **Enter**:
+
+```
+pip install polarsteps-data-parser
+```
+
+You only have to do this once, it installs the tool onto your computer.
+
+## **Step 4: Export Your Trip Data from Polarsteps**
+
+You need the data from your Polarsteps trip.
+
+1. Go to [Polarsteps.com](https://www.polarsteps.com/) and log in.
+1. Click on your profile and go to the 'Account settings'.
+1. Download the ZIP file via 'Download my data' in the Privacy section.
+1. Go the the downloads folder on your computer and **extract** (right-click the ZIP file and choose **Extract All**).
+1. Inside the newly created folder, there will be two folders: `trip` and `user`.
+1. Navigate inside the `trip` folder and locate the trip you want to convert to a PDF (for example `guatemala_12345678`).
+
+👉 Let’s say you extracted the folder to `Documents`. You will need to pass the following path to the program:
+
+`C:\Users\YourName\Documents\PolarstepsTriptrip\guatemala_12345678` (Windows)
+
+or
+
+`/Users/YourName/Documents/PolarstepsTrip/trip/guatemala_12345678/` (Mac)
+
+
+## **Step 5: Run the Program**
+
+Back in your command prompt / terminal, navigate to where your trip folder is located.
+
+### On **Windows**
+
+```
+cd "C:\Users\YourName\Documents"
+```
+
+### On **Mac/Linux**
+
+```
+cd /Users/YourName/Documents
+```
+
+Now run this command to generate the PDF:
+
+```
+polarsteps-data-parser "C:\Users\YourName\Documents\PolarstepsTriptrip\guatemala_12345678"
+```
+
+✅ This will create a PDF called **Trip report.pdf** inside the `Documents` folder (where you ran the command).
+
+---
+
+### **Optional: Customize the Output PDF Name**
+
+If you want the PDF to have a custom name (for example, "Guatemala Trip.pdf"), run:
+
+```
+polarsteps-data-parser "<path>" --output "Guatemala Trip.pdf"
+```
+
+## **Step 6: Open and Enjoy Your Trip Report**
+
+The program will create a **PDF** file, just open it like any regular document. You can view it, print it, or share it!
+
+---
+
+## **Troubleshooting**
+
+* **Command not found?**
+  Close the command prompt/terminal and open it again. Make sure Python is properly installed.
+
+* **Missing files?**
+  Ensure the folder has both `trip.json` and `locations.json`. The program needs both.
+
+* **Program updates?**
+  If you want to update the program later, simply run:
+
+  ```
+  pip install --upgrade polarsteps-data-parser
+  ```