From b57056964c6be846f984aaaaabe86023d4a335d1 Mon Sep 17 00:00:00 2001 From: Christian Gass Date: Thu, 8 Mar 2018 13:49:38 -0500 Subject: [PATCH] updated docs --- README.md | 106 ++++++++++++++++++++++++++++++------------ app/__init__.py | 6 +-- app/config.example.py | 19 ++------ 3 files changed, 82 insertions(+), 49 deletions(-) diff --git a/README.md b/README.md index 91febdb..3a61701 100644 --- 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 `