From a468d9ea42aa17af1bd5963e881a6dd165fa0c78 Mon Sep 17 00:00:00 2001
From: t-downing <downing.tristan@gmail.com>
Date: Fri, 1 Nov 2024 11:18:56 -0700
Subject: [PATCH] update readme

---
 ...-floodexposure-monitoring(development).yml | 10 +--
 README.md                                     | 74 +++++++++++++++++++
 2 files changed, 79 insertions(+), 5 deletions(-)

diff --git a/.github/workflows/development_chd-ds-floodexposure-monitoring(development).yml b/.github/workflows/development_chd-ds-floodexposure-monitoring(development).yml
index 4dd4931..c6db786 100644
--- a/.github/workflows/development_chd-ds-floodexposure-monitoring(development).yml
+++ b/.github/workflows/development_chd-ds-floodexposure-monitoring(development).yml
@@ -26,10 +26,10 @@ jobs:
         run: |
           python -m venv venv
           source venv/bin/activate
-      
+
       - name: Install dependencies
         run: pip install -r requirements.txt
-        
+
       # Optional: Add step to run tests here (PyTest, Django test suites, etc.)
 
       - name: Zip artifact for deployment
@@ -49,7 +49,7 @@ jobs:
     environment:
       name: 'development'
       url: ${{ steps.deploy-to-webapp.outputs.webapp-url }}
-    
+
     steps:
       - name: Download artifact from build job
         uses: actions/download-artifact@v4
@@ -59,11 +59,11 @@ jobs:
       - name: Unzip artifact for deployment
         run: unzip release.zip
 
-      
+
       - name: 'Deploy to Azure Web App'
         uses: azure/webapps-deploy@v3
         id: deploy-to-webapp
         with:
           app-name: 'chd-ds-floodexposure-monitoring'
           slot-name: 'development'
-          publish-profile: ${{ secrets.AZUREAPPSERVICE_PUBLISHPROFILE_B1801DFA53B94BF582030E652ECE2CAA }}
\ No newline at end of file
+          publish-profile: ${{ secrets.AZUREAPPSERVICE_PUBLISHPROFILE_B1801DFA53B94BF582030E652ECE2CAA }}
diff --git a/README.md b/README.md
index 410472c..6e051c4 100644
--- a/README.md
+++ b/README.md
@@ -3,3 +3,77 @@
 ## About
 
 App showing estimated flood exposure based on WorldPop and Floodscan.
+
+## Usage
+
+Running the app locally:
+
+1. Install the dependencies with `pip install -r requirements.txt`
+2. Install the local package with `pip install -e .`
+3. Set environment variables `DEV_BLOB_SAS` and `PROD_BLOB_SAS` to the SAS
+token for the blob storage account.
+4. Run the app with `python app.py` for debugging, or
+`gunicorn -w 4 -b 127.0.0.1:8000 app:server` for production.
+
+## Structure
+<!-- markdownlint-disable -->
+```plaintext
+.
+├── .github/
+│   └── workflows/
+│       └── ...          # build and deploy workflow
+├── assets/
+│   └── ...              # images, icon, CSS
+├── callbacks/
+│   └── callbacks.py     # single function to register all callbacks
+├── components/
+│   ├── alerts.py        # alerts at top of app
+│   ├── dropdowns.py     # dropdown menus (options usually populated by callback)
+│   ├── plots.py         # initialization of dcc.Graph components, content populated by callback
+│   └── text.py          # text in app
+├── data/
+│   ├── data/
+│   │   └── ...          # local data used in app (CODABs only)
+│   └── load_data.py     # functions to load data into app, and migrate data from blob to repo
+├── endpoints/
+│   └── endpoints.py     # single endpoint to reload data
+├── layouts/
+│   ├── content.py       # main body of app
+│   └── navbar.py        # just the top navbar
+├── src/
+│   ├── datasources/
+│   │   ├── codab.py     # loading CODABs from blob
+│   │   └── floodscan.py # loading Floodscan from blob
+│   ├── utils/
+│   │   └── blob.py      # loading data from blob
+│   └── constants.py     # list of countries, other constants
+├── app.py               # entrypoint for app
+└── index.py             # initializes app layout
+```
+<!-- markdownlint-enable -->
+
+## Development
+
+All code is formatted according to black and flake8 guidelines.
+The repo is set-up to use pre-commit.
+Before you start developing in this repository, you will need to run
+
+```shell
+pre-commit install
+```
+
+The `markdownlint` hook will require
+[Ruby](https://www.ruby-lang.org/en/documentation/installation/)
+to be installed on your computer.
+
+You can run all hooks against all your files using
+
+```shell
+pre-commit run --all-files
+```
+
+It is also **strongly** recommended to use `jupytext`
+to convert all Jupyter notebooks (`.ipynb`) to Markdown files (`.md`)
+before committing them into version control. This will make for
+cleaner diffs (and thus easier code reviews) and will ensure that cell outputs aren't
+committed to the repo (which might be problematic if working with sensitive data).