updated docs

civicmapper · Mar 8, 2018 · b570569 · b570569
1 parent 574a6a1
commit b570569
Show file tree

Hide file tree

Showing 3 changed files with 82 additions and 49 deletions.
diff --git a/README.md b/README.md
@@ -2,18 +2,46 @@
 
 A simple map-based application for estimating the power potential of microhydropower installations.
 
-## Software
+## Architecture Overview
 
 The Bard Microhydropower Calculator is built with Python-Flask, Leaflet, Esri-Leaflet, Bootstrap, and jQuery. Data and Geoprocessing services are from the Esri Living Atlas in ArcGIS Online (AGOL).
 
-### Development Quickstart
+Python Flask provides a server-side framework for assembling the web application from templates and assets. Since this is a single page app, it doesn't have much to do in that regard. Rather, its role is primarily to serve as a proxy for authenticating into secured Esri ArcGIS Online (AGOL) resources. It retrieves an AGOL authentication token on page load and returns it to the client side code (javascript), where it is used to make calls to elevation and other data services from Esri.
+
+On the front-end:
+
+* Bootstrap and jQuery provides the stack for the mobile-adaptive layout
+* Leaflet is used for the map
+* Esri-Leaflet helps utilize Esri services in conjunction with the Leaflet map
+
+Front-end business logic is written in javascript with only jQuery. Javascript and CSS compliation and bundling is being handled by GulpJS and Browserify.
+
+## Development
+
+### Configuration (`config.py`)
+
+The application requires a few global configuration variables to be set, mainly to enable access to 3rd-party services.
+
+See `app/config.py` for more information.
+
+_to be completed._
+
+#### ArcGIS Application Registration
+
+* Esri Application ID
+* Esri Application Secret
+
+#### Mapbox Token
+
+* Token
 
-This application requires Python 3.4 or later. Client-side javascript dependencies are included with the repository, so no javascript build system (e.g., Node/NPM) is currently necessary. However that _should_ change in the future; more on that later.
+### Quickstart
 
-This quickstart assumes you have:
+To develop this, you must have installed:
 
-* a working installation of Python 3.4+,
-* you can call `python` and `pip` or (`python -m pip`) from the command line
+* Python 3.4+, and you can call `python` and `pip` or (`python -m pip`) from the command line
+* Node/NPM and you can call `node` and `npm` from the command line
+* GulpJS installed (available via `npm`)
 * `git` installed, also available from the command line.
 
 1.  Clone the repository.
@@ -23,7 +51,7 @@ git clone https://github.com/civicmapper/bard-hydropower
 cd bard-hydropower
 ```
 
-1.  Initialize a Python virtual environment and install dependencies with Python `pipenv`:
+1.  Initialize a Python virtual environment and install Python dependencies with Python `pipenv`:
 
 If you don't have `pipenv` (and you won't with an out-of-the-box python installation)
 
@@ -39,52 +67,70 @@ pipenv install
 
 ...to install dependencies, and then:
 
+1.  Run a basic development server:
+
 ```shell
-pipenv shell
+pipenv shell python run.py
 ```
 
-...to activate the virtual environment.
+Navigate to [http://localhost:5000](http://localhost:5000) to see the site.
+
+Note that this only serves up compiled client-side code built stored with the repository. It does not run the client-side build tasks.
+
+You can kill this development server by pressing `ctrl-c` in the command line.
+
+### Client-Side Development
 
-1.  Run the development server:
+(assuming you've installed Python dependencies above)
 
-Within the `pipenv shell`:
+1.  Install javascript dependencies
+
+In the repository root:
 
 ```shell
-python run.py
+npm install
 ```
 
-Navigate to [http://localhost:5000](http://localhost:5000) to see the site.
+This will download and install a whole lot of javascript in a `node_modules` folder.
 
-### Architecture
+2.  Run a browser-synced development server
 
-Python Flask provides a server-side framework for assembling the web application from templates and assets. Since this is a single page app, it doesn't have much to do in that regard. Rather, its role is primarily to serve as a proxy for authenticating into secured Esri ArcGIS Online (AGOL) resources. It retrieves an AGOL authentication token on page load and returns it to the client side code (javascript), where it is used to make calls to elevation and other data services from Esri.
+```shell
+gulp watch
+```
 
-On the front-end:
+This does a bunch of things:
 
-* Bootstrap and jQuery provides the stack for the mobile-adaptive layout
-* Leaflet is used for the map
-* Esri-Leaflet helps utilize Esri services in conjunction with the Leaflet map
+* it compiles and bundles `js` files from the `src` and `node_modules` directory, and puts them in the the `app/static` directory (where the application wants them to be)
+* it does the same with `css` files
+* it copies assets from certain `js` modules to the `app/static/assets` directory,
+* it fires up the Python-Flask application and its development web server for you (runs `pipenv shell python run.py`)
+* it opens up your default browser and loads the page.
 
-Front-end business logic is written in javascript with only jQuery. Javascript bundling for _business-logic only_ is being handled by the Flask plugin Flask-Assets.
+3.  Develop and see changes as they happen
 
-NOTE: Currently, all javascript (including 3rd party dependencies like Leaflet) are being loaded through standard `<script>` tags in the `html`. In the future 3rd-party dependencies should installed with `npm`, explicitly imported into the business logic scripts, and all should be bundled with a task runner like Gulp, Webpack, or Rollup.
+With #2 complete, when you change code in the `src` folder, the browser will either:
 
-### Configuration (`config.py`)
+* live reload (inserting your changes into the page)
+* refresh automatically (if it needs to reload an entire script or asset again)
 
-#### ArcGIS Application Registration
+## Build
+
+Use `gulp build` from the command line to compile source code and copy assets in the `app` folder. Once built, only the `app` folder (and its contents) and `application.py` script are required for running the web application in production.
+
+Make sure your `config.py` `DEBUG` parameter is set to `False` for production!
 
-_to be completed_
+## Deployment
 
-* Application ID
-* Application Secret
+There are many ways to deploy this application. Some options:
 
-### Deployment
+### PythonAnywhere
 
-There are many ways to deploy this application. [PythonAnywhere](https://www.pythonanywhere.com/) provides a great place for deploying Flask applications like this. This one could also easily be deployed to AWS Elastic Beanstalk.
+[PythonAnywhere](https://www.pythonanywhere.com/) provides a great place for deploying a Flask applications like this. Follow [this](https://help.pythonanywhere.com/pages/Flask/) guide for deployment.
 
-#### Deployment to AWS Elastic Beanstalk
+### Deployment to AWS Elastic Beanstalk
 
-Follow [this](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/create-deploy-python-flask.html) guide for deployment.
+Follow [this](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/create-deploy-python-flask.html) guide for deployment to AWS EBS.
 
 As of this writing, AWS Elastic Beanstalk supports Python 3.4.
 

diff --git a/app/__init__.py b/app/__init__.py
@@ -1,7 +1,3 @@
-#----------------------------------------------------------------------------#
-# APP CONFIGURATION
-#----------------------------------------------------------------------------#
-
 # standard library imports
 
 import os
@@ -15,7 +11,7 @@
 import pdb
 
 #----------------------------------------------------------------------------
-# APPLICATION CONFIG
+# APPLICATION SETUP
 
 app = Flask(__name__)
 app.config.from_pyfile('config.py')

diff --git a/app/config.example.py b/app/config.example.py
@@ -1,23 +1,14 @@
 # project/_config.py
-
-import os
-from datetime import timedelta
-
-# Grabs the folder where the script runs.
-basedir = os.path.abspath(os.path.dirname(__file__))
-
-# Enable debug mode.
+# Enable debug mode. Be sure to set this to false for production!
 DEBUG = True
 
-# Secret key for session management.
+# Secret key for session management. Make sure this is long and very random.
 SECRET_KEY = ""
 
-# Session lifetime (matches lifetime of Esri tokens)
-# PERMANENT_SESSION_LIFETIME = timedelta(seconds=3600)
-
-# ESRI IDs for accessing premium AGOL services (elevation and hydrology)
+# ESRI IDs for accessing premium AGOL services (elevation and hydrology).
+# Get this by registering an application with from developers.arcgis.com.
 ESRI_APP_CLIENT_ID = ''
 ESRI_APP_CLIENT_SECRET = ''
 
-# MAPBOX Token for better custom basemaps
+# MAPBOX Token for custom basemaps. Get this from www.mapbox.com.
 MAPBOX_ACCESS_TOKEN = ""