Merge pull request #30 from cyiallou/feat/open-source-basic-notebooks

Open source basic Alert and Solar Notebooks

Author: cyiallou

RELEASE_NOTES.md

@@ -11,6 +11,8 @@
 ## New Features
 
 - Improved MIME type detection for email attachments, with a fallback for unknown file types.
+- Introduced a new alerts module for generating and formatting alert emails.
+- Added basic Alert and Solar Maintenance notebooks with instructions in English and German. These notebooks are aimed for running in a Deepnote project as they contain Deepnote related UI elements but they can also run in a common jupyter environment if the Deepnote UI elements are discarded.
 
 ## Bug Fixes
 

examples/Alerts Notebook.ipynb

@@ -0,0 +1,123 @@
+## **Anleitung: Deepnote Projekt erstellen und Notebook importieren**
+
+---
+
+### **1\. Einloggen in Deepnote**
+
+Öffnen Sie [Deepnote](https://deepnote.com/) und loggen Sie sich mit Ihrem Account ein.
+
+### **2\. Neues Projekt erstellen**
+
+Wählen Sie oben in dem Seitenmenü den Workspace, in dem Sie das neue Projekt erstellen wollen.
+
+Klicken sie dann bei dem Menüpunkt Projects auf das “+” und dann auf “New Project”
+
+<img src="images/image1.png" width="25%">
+
+Das erstellte Projekt öffnet sich automatisch:
+
+<img src="images/image2.png" width="50%">
+
+### **3\. Ändern der verwendeten Python Version**
+
+Das Notebook benötigt Python 3.11. Da Deepnote standardmäßig neue Projekte mit Python 3.9 initialisiert, muss die Version geändert werden. 
+
+Dazu klicken sie unten links auf das Dropdown Feld in dem die Python Version angezeigt wird und wählen sie Python 3.11
+
+<img src="images/image3.png" width="25%">
+<img src="images/image4.png" width="50%">
+
+### **4\. Python Notebook hochladen**
+
+Klicken Sie im Menü Links im Reiter **Files** auf das **\+**, wählen sie die Option **Upload .ipynb file**
+
+<img src="images/image5.png" width="25%">
+
+Laden Sie die zugeschickte Python Notebook Datei (.ipynb) hoch.
+
+Das hochgeladene Notebook sollte nach einer Aktualisierung der Seite in Ihrem Browser im Seitenmenü unter Notebooks zu sehen sein (im Bild als „Solar Notebook“ angezeigt)..
+
+Das ursprüngliche leere Notebook hier “Notebook 1” wird nicht mehr benötigt und kann gelöscht werden.
+
+<img src="images/image6.png" width="25%">
+
+### **5\. Requirements installieren**
+
+Klicken Sie im Seitenmenü auf das hinzugefügte Notebook.
+
+Damit Ihre Daten angezeigt werden können, müssen vor der Verwendung noch Pakete installiert werden. 
+
+Führen Sie dazu die erste Codezelle durch einen Klick auf das blaue Dreieck aus oder platzieren Sie Ihren Cursor innerhalb der Codezelle und verwenden Sie die Tastenkombination „STRG \+ Eingabe“. Sie können die Paketversion durch die gewünschte ersetzen. 
+
+**Es ist immer eine gute Idee, die neueste Version zu installieren, da diese neue Funktionen und/oder wichtige Fehlerbehebungen enthalten kann.**
+
+Beispiel zur Installation von [`frequenz-lib-notebooks`](https://github.com/frequenz-floss/frequenz-lib-notebooks):
+
+<img src="images/image7.png" width="70%">
+
+Die Installation der benötigten Pakete kann einen Moment dauern. Danach sollte ein gelber Kasten unter dem Code zu sehen sein in dem steht:
+
+“Delete this cell and move packages "frequenz-lib-notebooks"
+
+Falls dies nicht der Fall ist, muss der Code Block durch erneutes Klicken auf das blaue Dreieck erneut ausgeführt werden.
+
+Klicken sie auf den blauen Link move packages "frequenz-lib-notebooks" to “requirements.txt”
+
+Die Requirements werden in dem Projekt jetzt automatisch für alle Notebooks erstellt, sodass sie beliebig viele Kopien des Notebooks erstellen können, ohne die Installation erneut durchführen zu müssen.
+
+### **6\. Microgrids.toml-Datei hochladen**
+
+Wenn Sie eine microgrids.toml-Datei oder eine andere Datei von uns erhalten haben, laden Sie diese bitte über Files \> Upload file in Ihr Projekt.
+
+<img src="images/image8.png" width="35%">
+
+### **7\. API Anmeldedaten hinterlegen**
+
+Damit das Notebook Ihre Daten anzeigen kann, müssen Sie zunächst noch eine Integration Ihrer Kuiper API anlegen.
+
+Klicken Sie dazu im Seitenmenü links im Reiter **Integrations** auf das **\+** und wählen Sie   
+**Create a new integration.**
+
+Wählen Sie die Option Environment variables in dem sich öffnenden Dropdown.
+
+<img src="images/image9.png" width="25%">
+
+Geben Sie der Integration einen Namen ihrer Wahl und fügen Sie die unten aufgelisteten Key Value Pairs hinzu. 
+
+**Key**						**Value**
+
+REPORTING\_SERVER\_URL		grpc://reporting.api.frequenz.com:443
+
+REPORTING\_API\_KEY			Sie finden ihren API Key in Kuiper ([Anleitung](https://docs.google.com/document/u/0/d/1ePlCtr92pA1fRt2kt1PbyPs636ADk1r4PeuIOMBCM18/edit))
+
+WEATHER\_SERVER\_URL			grpc://fz-0003.frequenz.io:50052?ssl=false
+
+Bestätigen Sie ihre Eingabe durch klicken auf **Create integration**
+
+### 
+
+### **8\. App erstellen**
+
+Wenn Sie aus dem Notebook eine App erstellen möchten, können Sie dies tun, indem Sie oben rechts auf die Schaltfläche **Create app** klicken:
+
+<img src="images/image10.png" width="70%">
+
+Wählen sie folgende Einstellungen (diese sollten bereits voreingestellt sein) und bestätigen Sie mit einem Klicken auf **Create app:**
+
+<img src="images/image11.png" width="15%">
+
+### **9\. Führen Sie das Notebook aus**
+
+Befolgen Sie die im Notebook beschriebenen spezifischen Anweisungen.
+
+## **Anleitung: Planen Sie die regelmäßige Ausführung eine Notebook**
+
+---
+
+1\. Klicken Sie auf das Kalendersymbol **Schedule notebook**, das sich oben im Notizbuch befindet, direkt neben der Schaltfläche **Run notebook**.
+
+2\. Konfigurieren Sie die Häufigkeit, mit der das Notizbuch ausgeführt werden soll, und klicken Sie dann auf **Save schedule**.
+
+3\. Darüber hinaus können Sie auch Benachrichtigungen für erfolgreiche und fehlgeschlagene Ausführungen konfigurieren, entweder per E-Mail oder in Slack.
+
+<img src="images/image12.png" width="50%">

examples/Anleitung_ Deepnote Projekt erstellen und Notebook importieren.md

@@ -0,0 +1,121 @@
+## **Instructions: Create a Deepnote project and import a Notebook**
+
+---
+
+### **1\. Log in to Deepnote**
+
+Open [Deepnote](https://deepnote.com/) and log in with your account.
+
+### **2\. Create a new project**
+
+Select the workspace in which you want to create the new project in the side menu at the top.
+
+Then click on the “+” under the Projects menu item and then on “New Project”
+
+<img src="images/image1.png" width="25%">
+
+The newly created project opens automatically:
+
+<img src="images/image2.png" width="50%">
+
+### **3\. Changing the Python version**
+
+The Notebook requires Python 3.11. Since Deepnote initializes new projects with Python 3.9 by default, the version must be changed.
+
+To do this, click on the dropdown field at the bottom left where the Python version is displayed and select Python 3.11
+
+<img src="images/image3.png" width="25%">
+<img src="images/image4.png" width="50%">
+
+### **4\. Upload Python Notebook**
+
+Click on the \+ in the Files tab on the left menu and select the **Upload .ipynb file option.** Then upload the Python notebook file (.ipynb).
+
+<img src="images/image5.png" width="25%">
+
+The uploaded notebook should be visible in the side menu under Notebooks after refreshing the page in your browser (shown as “Solar Notebook” in the image).
+
+The original empty notebook here “Notebook 1” is no longer needed and can be deleted.
+
+<img src="images/image6.png" width="25%">
+
+### **5\. Install Requirements**
+
+Click on the added Notebook in the side menu.
+
+In order to display your data, packages must be installed before use.
+
+To do this, run the first code cell by clicking on the blue triangle or place your cursor inside the code cell and use the keyboard shortcut "CTRL \+ Enter". You can replace the package version with the one you want.
+
+**It is always a good idea to install the latest version as it may contain new features and/or important bug fixes.**
+
+Example for installing [`frequenz-lib-notebooks`](https://github.com/frequenz-floss/frequenz-lib-notebooks):
+
+<img src="images/image7.png" width="70%">
+
+Installing the required packages may take a moment. After that, you should see a yellow box under the code that says:
+
+“Delete this cell and move packages "frequenz-lib-notebooks"
+
+If this is not the case, the code block must be executed again by clicking on the blue triangle again.
+
+Click on the blue link move packages "frequenz-lib-notebooks" to “requirements.txt”
+
+The requirements are now automatically created for all notebooks in the project, so you can create as many copies of the notebook as you want without having to perform the installation again.
+
+### **6\. Upload other files**
+
+If you have received a microgrids.toml file or any other file from us please upload them to your project via Files \> Upload file.
+
+<img src="images/image8.png" width="35%">
+
+### **7\. Enter API login data**
+
+In order for the notebook to display your data, you must first create an integration of your Kuiper API.
+
+To do this, click on the \+ in the **Integrations** tab on the left in the side menu and select **Create a new integration**.
+
+Select the Environment variables option in the dropdown that opens.
+
+<img src="images/image9.png" width="25%">
+
+Give the integration a name of your choice and add the key value pairs listed below. 
+
+**Key**						**Value**
+
+REPORTING\_SERVER\_URL		grpc://reporting.api.frequenz.com:443
+
+REPORTING\_API\_KEY			You can find your API key in Kuiper ([Anleitung](https://docs.google.com/document/u/0/d/1ePlCtr92pA1fRt2kt1PbyPs636ADk1r4PeuIOMBCM18/edit))
+
+WEATHER\_SERVER\_URL			grpc://fz-0003.frequenz.io:50052?ssl=false
+
+Confirm your entry by clicking on **Create integration**.
+
+### 
+
+### **8\. Create app**
+
+If you want to create an app from the notebook then you can do so by clicking on the **Create app** button at the top right:
+
+<img src="images/image10.png" width="70%">
+
+Select the following settings (these should already be set) and confirm by clicking **Create app**:
+
+<img src="images/image11.png" width="15%">
+
+### **9\. Run the notebook**
+
+Follow the specific instructions described in the notebook.
+
+
+## **Instructions: Schedule regular notebook execution**
+
+---
+
+1\. Click the **Schedule notebook** calendar icon located at the top of the notebook, right next to the **Run notebook** button.
+
+2\. Configure the frequency at which you want the notebook to run, then click **Save schedule**.
+
+3\. In addition, you can also configure notifications for successful and failed runs, either via email or in Slack.
+
+<img src="images/image12.png" width="50%">

examples/Instructions_ Create a Deepnote project and import a notebook.md

@@ -0,0 +1,10 @@
+"""
+Alerts module for handling alert-related logic.
+
+This includes email generation, processing, and formatting. This module
+provides utilities to generate alert summaries, format alert details, and
+create structured HTML emails.
+
+Modules:
+    - alert_email: Functions to generate alert-related emails.
+"""