add readme

README.md

@@ -1,2 +1,128 @@
-# cal_heatmap
+# cal_heatmap: Yearly Calendar Heatmaps
 
+This project generates interactive yearly activity heatmaps using calendar data from a specified URL. It utilizes Streamlit for the web interface, Plotly for creating heatmaps, and other supporting libraries for data handling and visualization.
+
+## Features
+- Load calendar data from a given URL.
+- Save and load different configurations for calendar URL and number of years to display.
+- Generate interactive yearly heatmaps of events.
+- Customize the number of years to visualize.
+
+## Prerequisites
+
+- Python 3.9+
+- Required Python packages (listed in `requirements.txt`)
+
+## Installation
+
+1. **Clone the repository:**
+
+```sh
+git clone https://github.com/yourusername/yearly-activity-heatmaps.git
+cd yearly-activity-heatmaps
+```
+
+2. **Install the required packages:**
+
+```sh
+pip install -r requirements.txt
+```
+
+3. **Run the Streamlit app:**
+
+```sh
+streamlit run app.py
+```
+
+## Usage
+
+1. **Configure Settings:**
+   - Enter the calendar export link.
+   - Set the number of years to visualize.
+   - Save your configuration.
+
+2. **Generate Heatmaps:**
+   - The app will download the calendar data.
+   - It will parse the data and count events for each day.
+   - Interactive heatmaps will be generated for the specified years.
+
+## File Structure
+
+- `app.py`: Main script for running the Streamlit app.
+- `settings.json`: JSON file to store user configurations.
+- `requirements.txt`: List of required Python packages.
+
+## Project Dependencies
+
+Make sure you have the following Python libraries installed:
+
+- pandas
+- vobject
+- requests
+- datetime
+- matplotlib
+- calmap
+- streamlit
+- plotly
+
+You can install all dependencies using the following command:
+
+```sh
+pip install -r requirements.txt
+```
+
+## Docker Deployment
+
+1. **Build Docker Image:**
+
+```sh
+docker build -t yearly-activity-heatmaps .
+```
+
+2. **Run Docker Container:**
+
+```sh
+docker run -p 8501:8501 yearly-activity-heatmaps
+```
+
+This will build and run your Streamlit app inside a Docker container, exposing it on port 8501.
+
+## Example Code
+
+Below is a snippet of the core functionality in `app.py`:
+
+```python
+import pandas as pd 
+import vobject
+import requests
+from datetime import datetime, date
+import matplotlib.pyplot as plt
+import calmap
+import streamlit as st 
+import plotly.express as px
+import plotly.graph_objects as go
+import json
+import os
+
+# Functions to load and save data, create heatmaps, and update session state...
+
+# Set webpage title
+st.title("Yearly Activity Heatmaps")
+
+# Main logic for loading configurations, downloading calendar data, and generating heatmaps...
+
+# Plot each year's data
+for year in years_to_plot:
+    fig = create_calendar_heatmap(event_series, year)
+    st.plotly_chart(fig)
+```
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Acknowledgments
+
+- Streamlit for providing a fantastic framework for building web apps.
+- Plotly for interactive data visualization capabilities.
+- All contributors and users for their support.