Reorganize applications and packages (nteract#2149)

* move applications to dedicated directory
* stop the prettierness on package.json
* cut back on building desktop app in packages build
* update all the READMEs
* eslintignore applications' node_modules
* use sensible naming to differentiate applications
* simplify naming of textual editing to prose
* simplify releasing instructions

.eslintignore

@@ -8,4 +8,5 @@ types/
 build/
 example-notebooks/
 packages/**/node_modules
+applications/**/node_modules
 coverage

.gitignore

@@ -36,7 +36,7 @@ dist/
 
 test/*.ipynb
 
-packages/desktop/bin/nteract-env
+applications/desktop/bin/nteract-env
 
 # Ignore lerna lock
 packages/*/yarn.lock

.prettierignore

@@ -0,0 +1 @@
+package.json

README.md

@@ -7,34 +7,30 @@
 [![slack in](https://slackin-nteract.now.sh/badge.svg)](https://slackin-nteract.now.sh)
 [![Greenkeeper badge](https://badges.greenkeeper.io/nteract/nteract.svg)](https://greenkeeper.io/)
 
-
 [**Users**](#installation---users) | [**Contributors and Development**](#installation---contributors-and-development) | [**Maintainers**](#for-maintainers-creating-a-release)
 
+## Intro
 
-## Overview
-
-Edit code cells, write markdown, visualize!
+nteract is first and foremost a dynamic tool to allow you flexibility in writing code, exploring data, and authoring text to accompany your explorations.
 
-Checkout our [Medium blog post](https://medium.com/nteract/nteract-revolutionizing-the-notebook-experience-d106ca5d2c38) to see what amazing things you can do with nteract.
+**Edit code, write prose, and visualize.** Share documents understood across the jupyter ecosystem, [all in the comfort of a desktop app](https://medium.com/nteract/nteract-revolutionizing-the-notebook-experience-d106ca5d2c38), or [explore new ways of working with compute](https://play.nteract.io). We support [jupyter kernels](https://github.com/jupyter/jupyter/wiki/Jupyter-kernels) locally on your system and on remote JupyterHubs via Binder.
 
-![nteract geojson](https://cloud.githubusercontent.com/assets/836375/18421299/d95ad398-783b-11e6-8b23-d54cf7caad1e.png)
+**NOTE: If you're here to install the desktop app**, visit [nteract.io](https://nteract.io) or the [releases page](https://github.com/nteract/nteract/releases/latest).
 
-Note: There will be :bug:s and quirks. Please come tell us about them!
+## Overview
 
-nteract is a literate coding environment that supports Python, R, JavaScript and [other Jupyter kernels](https://github.com/jupyter/jupyter/wiki/Jupyter-kernels). It wraps up the best of the web based Jupyter notebook and embeds it as a desktop application that allows you to open notebooks natively on your system. Double click a `.ipynb` on the desktop, use Spotlight on the Mac. It Just Works™
+This repository is a [monorepo](./doc/design/monorepo.md), which basically means that the repository hosts more than one module or application. In our case, we have two main directories:
 
-### Scope and goals
+```
+packages/ -- everything used as an individual library
+applications/ -- all the user facing applications
+```
 
-* Notebook environment to explore and get things done ✅
-* Standalone cross-platform desktop application ✅
-* One notebook document/narrative per window ✅
-* Work with any Jupyter kernel using message spec v5 ✅
-* Easy install with pre-configured Python3 ❌  and JavaScript ✅ runtimes
-* Grow an ecosystem of tooling to allow others to build their own platforms relying on the Jupyter specifications ✅
+`packages` has what you need to build new applications and `applications` has the desktop app, the play app, and a few more.
 
 ## Installation - Users
 
-Head to the [Releases](https://github.com/nteract/nteract/releases/latest) page and download the version for your OS.
+**NOTE: If you're here to install the desktop app**, visit [nteract.io](https://nteract.io) or the [releases page](https://github.com/nteract/nteract/releases/latest) to download the version for your OS.
 
 ## Installation - Contributors and Development
 
@@ -49,30 +45,36 @@ Feel free to post issues or chat in [Slack](https://nteract.slack.com/) ([reques
 
 ### Development
 
-To get started developing install a [python runtime](#python-runtime) then install [`nteract` in dev mode](#install-nteract-in-dev-mode).
+To get started developing, [set up the nteract monorepo](#set-the-monorepo-up-in-dev-mode).
 
-#### Python runtime
-
-At least for now, we need the python 3 kernel installed when hacking on nteract:
-
-```
-python3 -m pip install ipykernel
-python3 -m ipykernel install --user
-```
-
-#### Install `nteract` in dev mode
+#### Set the monorepo up in dev mode
 
 Requires [Node.js and npm 3+](https://docs.npmjs.com/getting-started/installing-node).
 
 1. Fork this repo
 2. Clone it `git clone https://github.com/nteract/nteract`
 3. `cd` to where you `clone`d it
 4. `npm install`
-5. `npm run start`
 
-As you make changes, close the entire app (cmd-q on OS X, or ctrl-c at the terminal) then run `npm run start` again.
+#### Building specific packages
 
-##### Progressive Webpack build for the notebook
+In some cases you'll want to modify a base package (and not rebuild everything). To target just one use this, replacing `packageName` with the package you want to hack on.
+
+```
+$(npm bin)/lerna run build --scope packageName
+```
+
+#### Hacking on the Desktop application
+
+##### Quick and dirty
+
+```
+npm run app:desktop
+```
+
+As you make changes, you will have to close the entire app (cmd-q on OS X, or ctrl-c at the terminal) then run `npm run app:desktop` again.
+
+##### Progressive Webpack build for the desktop notebook
 
 In separate terminals run:
 
@@ -88,28 +90,32 @@ npm run spawn
 
 The webpack build will keep occurring as you modify source. When you open a new notebook, you'll get the freshest copy of the notebook app.
 
-#### Build Documentation
-You can run nteract's documentation generator by running
+#### Hacking on `play`
+
+Run
 
 ```
-npm run build:docs
+npm run app:play
 ```
 
-And then opening `docs/index.html` in your favorite browser.
+Then open `127.0.0.1:3000` in your browser. You'll be able to make changes to play and see them
+update live.
+
+If you make changes to any `packages/` you'll want to rebuild those using [the instructions for building specific packages](#building-specific-packages).
 
 #### Troubleshooting
 
 > I upgraded my developer installation and things are broken!
 
-- Try `git clean -xdf && npm i`
+* Try `git clean -xdf && npm i`
 
 > I want to debug redux actions and state changes.
 
--  Enable [redux-logger](https://github.com/evgenyrodionov/redux-logger) by spawning the application with `npm run spawn:debug`.
+* Enable [redux-logger](https://github.com/evgenyrodionov/redux-logger) by spawning the application with `npm run spawn:debug`.
 
 > I keep getting 'Do you want the application "nteract Helper.app" to accept incoming network connections?' while developing or using a custom build of nteract on macOS.
 
--  This is how the the macOS firewall behaves for unsigned apps. On a signed app, the dialog won't show up again after approving it the first time. If you're using a custom build of nteract, run: `sudo codesign --force --deep --sign - /Applications/nteract.app`. You will have to do this again every time you rebuild the app.
+* This is how the the macOS firewall behaves for unsigned apps. On a signed app, the dialog won't show up again after approving it the first time. If you're using a custom build of nteract, run: `sudo codesign --force --deep --sign - /Applications/nteract.app`. You will have to do this again every time you rebuild the app.
 
 ## For maintainers: Creating a release
 

applications/desktop/README.md

@@ -0,0 +1,24 @@
+## Overview
+
+Edit code, write prose, visualize data!
+
+![nteract geojson](https://cloud.githubusercontent.com/assets/836375/18421299/d95ad398-783b-11e6-8b23-d54cf7caad1e.png)
+
+Checkout our [Medium blog post](https://medium.com/nteract/nteract-revolutionizing-the-notebook-experience-d106ca5d2c38) to see what amazing things you can do with nteract.
+
+Note: There will be :bug:s and quirks. Please come tell us about them!
+
+nteract is a literate coding environment that supports Python, R, JavaScript and [other Jupyter kernels](https://github.com/jupyter/jupyter/wiki/Jupyter-kernels). It wraps up the best of the web based Jupyter notebook and embeds it as a desktop application that allows you to open notebooks natively on your system. Double click a `.ipynb` on the desktop, use Spotlight on the Mac. It Just Works™
+
+### Scope and goals
+
+* Notebook environment to explore and get things done ✅
+* Standalone cross-platform desktop application ✅
+* One notebook document/narrative per window ✅
+* Work with any Jupyter kernel using message spec v5 ✅
+* Easy install with pre-configured Python3 ❌ and JavaScript ✅ runtimes
+* Grow an ecosystem of tooling to allow others to build their own platforms relying on the Jupyter specifications ✅
+
+## Installation - Users
+
+Head to the [Releases](https://github.com/nteract/nteract/releases/latest) page and download the version for your OS.

packages/desktop/RELEASING.md → applications/desktop/RELEASING.md

@@ -2,7 +2,8 @@
 
 ## All platform precursor
 
-To be able to publish a release you'll need to generate a GitHub access token by going to <https://github.com/settings/tokens/new>.  The access token should have the `repo` scope/permission.  Once you have the token, assign it to an environment variable (on macOS/linux):
+To be able to publish a release you'll need to generate a GitHub access token by going to <https://github.com/settings/tokens/new>. The access token should have the `repo` scope/permission. Once you have the token, assign it to an environment variable (on macOS/linux):
+
 ```bash
 export GH_TOKEN="<YOUR_TOKEN_HERE>"
 ```
@@ -15,20 +16,21 @@ In order to build a signed copy with working auto-update, you will need to join
 
 0. Run `lerna publish` to publish all the packages, or at the very least just this package, `nteract`.
 
-1. Make sure the release is working by running `npm run dist` and testing the built app inside the `./packages/desktop/dist/` folder. You can build for all platforms using `npm run dist:all`.
+1. Make sure the release is working by running `npm run dist` and testing the built app inside the `./applications/desktop/dist/` folder. You can build for all platforms using `npm run dist:all`.
 
-2. If everything works as expected, bump the version number in `./packages/desktop/package.json` and push the changes to GitHub. NOTE: If you already ran `lerna publish` and updated the version for the `nteract` package, you've already bumped this number!
+1. Run `npm run publish` on macOS, Windows and Linux or run `npm run publish:all` to build everything on a single machine. This will draft a new release on GitHub and will upload all necessary assets.
 
-3. Run `npm run publish` on macOS, Windows and Linux or run `npm run publish:all` to build everything on a single machine. This will draft a new release on GitHub and will upload all necessary assets.
+1. From GitHub go to [nteract's releases](https://github.com/nteract/nteract/releases), verify everything works and edit the release notes. The name should follow our [naming guidelines](https://github.com/nteract/naming), namely that we use the last name of the next scientist in the list with an adjective in front.
+   Example:
 
-4. From GitHub go to [nteract's releases](https://github.com/nteract/nteract/releases), verify everything works and edit the release notes. The name should follow our [naming guidelines](https://github.com/nteract/naming), namely that we use the last name of the next scientist in the list with an adjective in front.
-Example:
 ```bash
 Last release: Avowed Avogadro
 Next Scientist: Babbage
 Next release: Babbling Babbage
 ```
+
 My favorite way to pick the alliterative adjectives is using the local dictionary and our friend `grep`:
+
 ```bash
 $ cat /usr/share/dict/words | grep "^babb"
 babbitt

packages/nbextension/package.json → applications/jupyter-extension/package.json

@@ -8,7 +8,7 @@
     "prebuild:python": "rimraf dist",
     "publish": "echo 'not really publishing'"
   },
-  "repository": "https://github.com/nteract/nteract/tree/master/packages/nbextension",
+  "repository": "https://github.com/nteract/nteract/tree/master/applications/jupyter-extension",
   "publishConfig": {
     "access": "public",
     "dry-run": true

packages/play.nteract.io/package.json → applications/play/package.json

@@ -3,6 +3,7 @@
   "version": "1.0.5",
   "description": "a playground for execution",
   "main": "index.js",
+  "repository": "https://github.com/nteract/nteract/tree/master/applications/play",
   "scripts": {
     "dev": "next",
     "build": "next build",

doc/design/monorepo.md

@@ -0,0 +1,26 @@
+# Why is nteract a monorepo?
+
+> The tool for managing the monorepo in nteract is [Lerna](https://github.com/lerna/lerna)
+
+Juggling a multimodule project over multiple repos is like trying to teach a newborn baby how to
+ride a bike.
+
+nteract follows a monorepo approach, all officially maintained modules are in the same repo.
+
+**Pros:**
+
+ * Single lint, build, test and release process.
+ * Easy to coordinate changes across modules.
+ * Single place to report issues.
+ * Easier to setup a development environment.
+ * Tests across modules are ran together which finds bugs that touch multiple modules easier.
+
+**Cons:**
+
+ * Codebase looks more intimidating.
+ * Repo is bigger in size.
+ * [Can't `npm install` modules directly from GitHub](https://github.com/npm/npm/issues/2974)
+
+## This is weird! Nobody in open source does this!
+
+[React](https://github.com/facebook/react/tree/master/packages), [Meteor](https://github.com/meteor/meteor/tree/devel/packages), [Ember](https://github.com/emberjs/ember.js/tree/master/packages), [Babel](https://github.com/babel/babel/blob/master/doc/design/monorepo.md) among others, do this.

lerna.json

@@ -1,15 +1,19 @@
 {
-  "lerna": "2.1.2",
-  "packages": ["packages/*", "packages/nbextension/nteract_on_jupyter"],
+  "lerna": "2.4.0",
+  "packages": [
+    "packages/*",
+    "applications/*",
+    "applications/jupyter-extension/nteract_on_jupyter"
+  ],
   "version": "independent",
   "npmClient": "npm",
   "commands": {
     "publish": {
       "ignore": [
         "packages/desktop/*",
-        "packages/nbextension/*",
-        "packages/desktop/**",
-        "packages/play.nteract.io/*"
+        "packages/jupyter-extension/*",
+        "applications/desktop/**",
+        "applications/play/**"
       ]
     }
   }

package.json

@@ -33,10 +33,9 @@
     "build": "npm run build:packages && npm run build:desktop",
     "build:desktop": "lerna run build --scope nteract --stream",
     "build:desktop:watch": "lerna run build:watch --scope nteract --stream",
-    "build:packages": "lerna run build --parallel --ignore @nteract/play --ignore @nteract/showcase",
-    "build:packages:watch": "lerna run build:lib:watch --parallel --ignore @nteract/play --ignore @nteract/showcase",
+    "build:packages": "lerna run build --parallel --ignore @nteract/play --ignore @nteract/showcase --ignore nteract",
+    "build:packages:watch": "lerna run build:lib:watch --parallel --ignore @nteract/play --ignore @nteract/showcase --ignore nteract",
     "build:icon": "./scripts/make_icons.sh && cd static/icons && iconutil -c icns nteract.iconset && mv nteract.icns ../icon.icns",
-    "build:docs": "esdoc -c esdoc.json",
     "test": "jest",
     "test:unit": "npm run test",
     "test:coverage": "npm run test:unit -- --coverage",