From ffd4187a2a98b6ba5b5fb25e394663cd7b421716 Mon Sep 17 00:00:00 2001 From: Kade Cole Date: Thu, 10 Mar 2022 14:42:00 -0600 Subject: [PATCH] Update README.md --- README.md | 48 +++++++++++++++++++++++------------------------- 1 file changed, 23 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index cd8cc64..78fd4fa 100644 --- a/README.md +++ b/README.md @@ -3,37 +3,35 @@ > A Python code example for building web apps without writing HTML, CSS. and JavaScript.
- python logo + python logo - altair viz logo - + altair viz logo - fast ai logo + fast ai logo - ipywidgets + ipywidgets - jupyter logo + jupyter logo - voila logo + voila logo - docker logo + docker logo
-Got a Python project or Jupyter notebook? Want to turn it into a web applilcation? +### Got a Python project or Jupyter notebook? Want to turn it into a web applilcation? -<<<<<<< HEAD -This repository contains easy-to-modify [Python](https://www.python.org/) code. It demonstrates using [ipywidgets](https://ipywidgets.readthedocs.io/en/stable/) to build an interactive web application. It relies on [Jupyter](https://jupyter.org/) notebook infrasturcture. However, the app looks like a web app, not a notebook. Further, it demonstrates the use of [Docker](https://www.docker.com/) and [Voilà](https://github.com/voila-dashboards/voila) to allow the app to be hosted on composable infrastructure. The example code uses [pandas](https://pandas.pydata.org/) for data access and [Matplotlib](https://matplotlib.org/) to generate plots. +This repository contains easy-to-modify [Python](https://www.python.org/) code. It demonstrates using [ipywidgets](https://ipywidgets.readthedocs.io/en/stable/) to build an interactive web application. It relies on [Jupyter](https://jupyter.org/) notebook infrastructure. However, the app looks like a web app, not a notebook. Further, it demonstrates the use of [Docker](https://www.docker.com/) and [Voilà](https://github.com/voila-dashboards/voila) to allow the app to be hosted on composable infrastructure. The example code uses [pandas](https://pandas.pydata.org/) for data access and [Matplotlib](https://matplotlib.org/) to generate plots. -The template was developed so researchers can quickly and easily put their project on the web without getting bogged down in conventional web developement (AJAX, HTML, CSS, JS, etc.). The example notebook uses global temperature data from NASA to show how users can view, search, download, and plot data using an interactive, web enabled tool. +The template was developed so researchers can quickly and easily put their project on the web without getting bogged down in conventional web development (AJAX, HTML, CSS, JS, etc.). The example notebook uses global temperature data from NASA to show how users can view, search, download, and plot data using an interactive, web enabled tool. ## Opinionated Development Environment -[nbdev](https://nbdev.fast.ai/) is a library originally intended to allow developers to develop python libraries from Jupyter Notebooks. The advantage of this approach is that the resulting programming environment is truely literate: all code, tests, and documentation are produced from a narrative-style composition. +[nbdev](https://nbdev.fast.ai/) is a library originally intended to allow developers to develop python libraries from Jupyter Notebooks. The advantage of this approach is that the resulting programming environment is truly literate: all code, tests, and documentation are produced from a narrative-style composition. -Development in Notebooks is often eshewed by programmers who have a prefered IDE or development environment that has useful features such as grammar check, auto-complete, navigating by definitions, or searching code. This is a fair point, though as we will see, many or all of these features can be reclaimed through the use of extensions. +Development in Notebooks is often eschewed by programmers who have a preferred IDE or development environment that has useful features such as grammar check, auto-complete, navigating by definitions, or searching code. This is a fair point, though as we will see, many or all of these features can be reclaimed through the use of extensions. -Weighing benefits and drawbacks of the use of notebooks to develop a simple library is not in the scope of this template. However, the development of a user interface in Jupyter built with ipywidgets is more cumbersome. Though the creators of nbdev may not have intended it, this library is also excellent for developing interactive applications build with [ipywidgets](https://ipywidgets.readthedocs.io/en/stable/). Because interactive widgets make heavy use of callback functions, the use of debuggers is difficult. Additionally, the notebook kernel must be restarted to propogate changes made to the codebase. We claim that nbdev is best suited to ameliorate the following tiresome development procedure: +Weighing benefits and drawbacks of the use of notebooks to develop a simple library is not in the scope of this template. However, the development of a user interface in Jupyter built with ipywidgets is more cumbersome. Though the creators of nbdev may not have intended it, this library is also excellent for developing interactive applications build with [ipywidgets](https://ipywidgets.readthedocs.io/en/stable/). Because interactive widgets make heavy use of callback functions, the use of debuggers is difficult. Additionally, the notebook kernel must be restarted to propagate changes made to the codebase. We claim that nbdev is best suited to ameliorate the following tiresome development procedure: 1. Change a single line of code in a python script 2. Restart rerun the application notebook @@ -44,28 +42,28 @@ This procedure is obviated by the use of nbdev, which allows the developer to de ## Development ### Getting Started -1. Click the "Use This Template" Button in GitHub to create a copy of this repo of your own. +1. Click the [Use This Template](https://github.com/kadecole/nbdev_app_template/generate) button in GitHub to create a copy of this repo. 1. Install [Docker](https://docs.docker.com/get-docker/) on your workstation. Note that you may need admin access to run Docker commands. 1. Start a command line (terminal) session. -1. Make sure Docker is running by entering: [`docker info`](https://docs.docker.com/config/daemon/). -1. Run `docker-compose up jupyterlab` to start the JupyterLab server. -1. Copy the URL starting with "http://localhost..." into your local browser. This URL ends with long token you will need to access the session. +1. Make sure Docker is running by entering [`docker info`](https://docs.docker.com/config/daemon/). +1. Run `docker-compose up jupyterlab` to start the [JupyterLab](https://jupyterlab.readthedocs.io/en/stable/) server. +1. Copy the URL starting with "http://localhost..." into your local browser. This URL ends with a long token you will need to access the JupyterLab session. ### Developing on a Remote server -If you need to develop your application on a remote server - such as a compute cluster - you will need to use ssh port forwarding in order to access the notebook from the browser on your local machine. +If you need to develop your application on a remote server (node) - such as a compute cluster - you will need to use ssh port forwarding in order to access the notebook from the browser on your local machine. 1. SSH into the remote node using `ssh -L 8888:localhost:8888 @` -1. Follow the steps in [Getting Started](#getting-started) ***on the remote node*** you just logged into. Docker may already be installed there. You can check for it by running `docker info`. +1. Follow the steps in [Getting Started](#getting-started) ***on the remote node*** you just logged into. Docker may already be installed and you can check by running `docker info`. -### Installing dependecies -Install any dependencies you need by adding them to the environment.yml file in the root directory and rebuilding the docker image. +### Installing dependencies +Install any dependencies you need by adding them to the [environment.yml](environment.yml) file in the root directory and rebuilding the docker image. ### Upload container -To allow others to run your app, it must be hosted on a publicly available Docker hosting system. There are a wide variety of options available including commercial sites like Amazon's AWS. Some institutions maintain their own Docker hosting systems. Depending on the specific reqirements of the hosting system you select, you'll need to provide either: +To allow others to run your app, it must be hosted on a publicly available Docker hosting system. There are a wide variety of options available including commercial sites like Amazon's AWS. Some institutions maintain their own Docker hosting system. Depending on the specific requirements of the hosting system you select, you'll need to provide either: - a `Dockerfile` similar to [Dockerfile-voila](Dockerfile-voila) -- a Docker image that can [hosted and pulled from Docker Hub](https://docs.docker.com/docker-hub/). +- a Docker image that can be [hosted and pulled from Docker Hub](https://docs.docker.com/docker-hub/). You might be required to access the host system's Kubernetes management system (e.g. Rancher) to create the container and allocate resources. ## Attributions