Merge pull request #865 from blink1073/docs-audit

Reorganize the top level documentation

CONTRIBUTING.md

@@ -1,5 +1,197 @@
-# Contributing
+# Contributing to JupyterLab
 
-We follow the [IPython Contributing Guide](https://github.com/ipython/ipython/blob/master/CONTRIBUTING.md).
+If you're reading this section, you're probably interested in contributing to
+JupyterLab.  Welcome and thanks for your interest in contributing!
+
+Please take a look at the Contributor documentation, familiarize yourself with
+using the Jupyter Notebook, and introduce yourself on the mailing list and share
+what area of the project you are interested in working on.
+
+## General Guidelines
+
+For general documentation about contributing to Jupyter projects, see the
+[Project Jupyter Contributor Documentation](http://jupyter.readthedocs.io/en/latest/contributor/content-contributor.html).
 
 All source code is written in [TypeScript](http://www.typescriptlang.org/Handbook). See the [Style Guide](https://github.com/jupyter/jupyterlab/wiki/TypeScript-Style-Guide).
+
+
+## Setting Up a Development Environment
+
+### Installing Node.js and npm
+
+Building the Notebook from its GitHub source code requires some tools to
+create and minify JavaScript components and the CSS.
+Namely, that's Node.js and Node's package manager, ``npm``.
+
+If you use ``conda``, you can get them with:
+
+```bash
+conda install -c javascript nodejs
+```
+
+If you use [Homebrew](http://brew.sh/) on Mac OS X:
+
+```bash
+brew install node
+```
+
+For Debian/Ubuntu systems, you should use the ``nodejs-legacy`` package instead
+of the ``node`` package:
+
+```bash
+sudo apt-get update
+sudo apt-get install nodejs-legacy npm
+```
+
+You can also use the installer from the [Node.js](https://nodejs.org) website.
+
+
+## Installing JupyterLab
+
+JupyterLab requires Jupyter Notebook version 4.2 or later.
+
+If you use ``conda``, you can install it as:
+
+```bash
+conda install notebook
+```
+
+If you use ``pip``` you can install it as:
+
+```bash
+pip install notebook
+```
+
+Once you have installed the dependencies mentioned above, use the following
+steps::
+
+    git clone https://github.com/<your-github-username>/jupyterlab.git
+    cd jupyterlab
+    npm install
+    pip install -e . # will take a long time to build everything
+    jupyter serverextension enable --py jupyterlab
+
+
+
+Note: At times, it may be necessary to clean your local repo with the 
+command ``git clean -fdx``.
+
+### Run JupyterLab
+
+Start JupyterLab:
+
+```bash
+jupyter lab
+```
+
+Alternatively, you can run JupyterLab in debug mode:
+
+```bash
+jupyter lab --debug
+```
+
+### Run the tests
+
+```bash
+npm test
+```
+
+### Build and run the stand-alone examples
+
+To install and build the examples in the `examples` directory:
+
+```bash
+npm run build:examples
+```
+
+To run a specific example, change to the example's directory (i.e.
+`examples/filebrowser`) and enter:
+
+```bash
+python main.py
+```
+
+### Build API Docs
+
+To build the [API docs](http://jupyter.github.io/jupyterlab/):
+
+```bash
+npm run docs
+```
+
+Navigate to `docs/index.html`.
+
+----
+
+## High level Architecture
+
+The JupyterLab application is made up of two major parts:
+
+- an npm package
+- a Jupyter server extension (Python package)
+
+Each part is named `jupyterlab`. The [developer tutorial documentation](http://jupyterlab-tutorial.readthedocs.io/en/latest/index.html)
+provides additional architecture information.
+
+## The NPM Package
+
+The npm package source files are in the `src/` subdirectory.
+
+**Prerequisites**
+- [node](http://nodejs.org/) (preferably version 5 or later)
+- Jupyter notebook server version 4.2 or later (to run examples)
+
+```bash
+npm install --save jupyterlab
+```
+
+### Build the NPM Package from Source
+
+```bash
+git clone https://github.com/jupyter/jupyterlab.git
+cd jupyterlab
+npm install
+npm run build:all
+```
+
+**Rebuild**
+
+```bash
+npm run clean
+npm run build:all
+```
+
+## The Jupyter Server Extension
+
+The Jupyter server extension source files are in the `jupyterlab/`
+subdirectory. To use this extension, make sure the Jupyter notebook server
+version 4.2 or later is installed.
+
+### Build the JupyterLab server extension
+
+When you make a change to JupyterLab npm package source files, run:
+
+```bash
+npm run build:serverextension
+```
+
+to build the changes and then refresh your browser to see the changes.
+
+To have the system build after each source file change, run:
+
+```bash
+npm run watch:serverextension
+```
+
+and refresh the browser.
+
+## Bundle for the Browser
+
+Follow the package install instructions first.
+
+Any bundler that understands how to `require()` files with `.js` and `.css`
+extensions can be used with this package.
+
+**Note:** This npm module is fully compatible with Node/Babel/ES6/ES5. Simply
+omit the type declarations when using a language other than TypeScript.
+

README.md

@@ -1,6 +1,16 @@
+**[Prerequisites](#prerequisites)** |
+**[Installation](#installation)** |
+**[Contributing](#contributing)** |
+**[License](#license)** |
+**[Getting help](#getting-help)**
+
+
 # [JupyterLab](http://jupyter.github.io/jupyterlab/)
 
+[![Build Status](https://travis-ci.org/jupyter/jupyterlab.svg?branch=master)](https://travis-ci.org/jupyter/jupyterlab)
 [![Binder](http://mybinder.org/badge.svg)](http://mybinder.org/repo/jupyter/jupyterlab/lab)
+[![Documentation Status](https://readthedocs.org/projects/jupyterlab-tutorial/badge/?version=latest)](http://jupyterlab-tutorial.readthedocs.io/en/latest/?badge=latest)
+[![Google Group](https://img.shields.io/badge/-Google%20Group-lightgrey.svg)](https://groups.google.com/forum/#!forum/jupyter)
 
 An extensible computational environment for Jupyter.
 
@@ -12,9 +22,9 @@ meets your workflow needs. Here's a quick preview of JupyterLab:
 
 <img src="jupyter-plugins-demo.gif" alt="JupyterLab Demo" style="width: 100%;"/>
 
-## Getting started
+----
 
-### Prerequisite
+## Prerequisites
 
 Jupyter notebook version 4.2 or later. To check the notebook version:
 
@@ -22,209 +32,68 @@ Jupyter notebook version 4.2 or later. To check the notebook version:
 jupyter notebook --version
 ```
 
-### User installation
-
-From the command line:
-
-```bash
-pip install jupyterlab
-jupyter serverextension enable --py jupyterlab --sys-prefix
-```
-
-Start up JupyterLab:
+### Supported Runtimes
 
-```bash
-jupyter lab
-```
-
-JupyterLab will open automatically in your browser. You may also access
-JupyterLab by entering the notebook server's URL (`http://localhost:8888`) in
-the browser.
-
-----
+The runtime versions which are currently *known to work*:
 
-## Documentation
+- IE 11+
+- Firefox 32+
+- Chrome 38+
 
-- [API Docs](http://jupyter.github.io/jupyterlab/)
-- [Architecture tutorial](http://jupyterlab-tutorial.readthedocs.io/en/latest/index.html)
+Earlier browser versions may also work, but come with no guarantees.
 
 ----
 
-## Contributing to JupyterLab
+## Installation
 
-### Setting up a development system
-
-#### Prerequisites
-
-- Jupyter notebook version 4.2 or later
-- NodeJS (preferably version 5 or later) and npm
-
-#### Installation
-
-Fork the JupyterLab repo using the GitHub UI. Clone the repo and build using these commands:
-
-```bash
-git clone https://github.com/<your-github-username>/jupyterlab.git
-cd jupyterlab
-npm install
-pip install -e . # will take a long time to build everything
-jupyter serverextension enable --py jupyterlab
-```
-
-Note: At times, it may be necessary to clean your local repo with the 
-command ``git clean -fdx``.
-
-### Run JupyterLab
-
-Start JupyterLab:
-
-```bash
-jupyter lab
-```
-
-Alternatively, you can run JupyterLab in debug mode:
+If you use ``conda``, you can install as:
 
 ```bash
-jupyter lab --debug
+conda install -c conda-forge jupyterlab
 ```
 
-### Run the tests
-
-```bash
-npm test
-```
-
-### Build and run the stand-alone examples
-
-To install and build the examples in the `examples` directory:
+If you use ``pip``, you can install it as:
 
 ```bash
-npm run build:examples
-```
-
-To run a specific example, change to the example's directory (i.e.
-`examples/filebrowser`) and enter:
-
-```bash
-python main.py
+pip install jupyterlab
+jupyter serverextension enable --py jupyterlab --sys-prefix
 ```
 
-### Build API Docs
-
-To build the [API docs](http://jupyter.github.io/jupyterlab/):
+Start up JupyterLab:
 
 ```bash
-npm run docs
+jupyter lab
 ```
 
-Navigate to `docs/index.html`.
+JupyterLab will open automatically in your browser. You may also access
+JupyterLab by entering the notebook server's URL (`http://localhost:8888`) in
+the browser.
 
 ----
 
-## High level Architecture
-
-The JupyterLab application is made up of two major parts:
-
-- an npm package
-- a Jupyter server extension (Python package)
-
-Each part is named `jupyterlab`. The [developer tutorial documentation](http://jupyterlab-tutorial.readthedocs.io/en/latest/index.html)
-provides additional architecture information.
-
-## The NPM Package
-
-The npm package source files are in the `src/` subdirectory.
-
-**Prerequisites**
-- [node](http://nodejs.org/) (preferably version 5 or later)
-- Jupyter notebook server version 4.2 or later (to run examples)
-
-```bash
-npm install --save jupyterlab
-```
-
-### Build the NPM Package from Source
-
-```bash
-git clone https://github.com/jupyter/jupyterlab.git
-cd jupyterlab
-npm install
-npm run build:all
-```
-
-**Rebuild**
-
-```bash
-npm run clean
-npm run build:all
-```
-
-## The Jupyter Server Extension
-
-The Jupyter server extension source files are in the `jupyterlab/`
-subdirectory. To use this extension, make sure the Jupyter notebook server
-version 4.2 or later is installed.
-
-### Build the JupyterLab server extension
+## Contributing
 
-When you make a change to JupyterLab npm package source files, run:
+If you would like to contribute to the project, please read our [contributor documentation](CONTRIBUTING.md).
 
-```bash
-npm run build:serverextension
-```
-
-to build the changes and then refresh your browser to see the changes.
-
-To have the system build after each source file change, run:
-
-```bash
-npm run watch:serverextension
-```
-
-and refresh the browser.
-
-## Bundle for the Browser
-
-Follow the package install instructions first.
-
-Any bundler that understands how to `require()` files with `.js` and `.css`
-extensions can be used with this package.
-
-**Note:** This npm module is fully compatible with Node/Babel/ES6/ES5. Simply
-omit the type declarations when using a language other than TypeScript.
-
-## Supported Runtimes
+----
 
-The runtime versions which are currently *known to work*:
+## License
+We use a shared copyright model that enables all contributors to maintain the
+copyright on their contributions.
 
-- IE 11+
-- Firefox 32+
-- Chrome 38+
-
-Earlier browser versions may also work, but come with no guarantees.
+All code is licensed under the terms of the revised BSD license.
 
-Note: "requirejs" must be included in a global context (usually as a
-`<script>` tag) for Comm targets.
-
-## Publishing packages for a JupyterLab release
+----
 
-We publish an npm package, a Python source package, and a Python universal binary wheel.  We also publish a conda package on conda-forge (see below).
-See the Python docs on [package uploading](https://packaging.python.org/distributing/#uploading-your-project-to-pypi) 
-for twine setup instructions and for why twine is the recommended method.
+## Getting help
+We encourage you to ask questions on the [mailing list](https://groups.google.com/forum/#!forum/jupyter),
+and you may participate in development discussions or get live help on [Gitter](https://gitter.im/jupyterhub/jupyterlab).
 
-```bash
-npm version patch
-git push origin master --tags
-npm publish
-rm -rf dist
-python setup.py sdist
-python setup.py bdist_wheel --universal
-twine upload dist/*
-md5 dist/*.tar.gz  # get the md5 hash for conda-forge install
-```
 
-Publish on conda-forge
+## Resources
 
-- Fork https://github.com/conda-forge/jupyterlab-feedstock
-- Create a PR with the version bump
-- Update `recipe/meta.yaml` with the new version and md5
+- [Reporting Issues](https://github.com/jupyter/jupyterlab/issues)
+- [API Docs](http://jupyter.github.io/jupyterlab/)
+- [Architecture tutorial](http://jupyterlab-tutorial.readthedocs.io/en/latest/index.html)
+- [Documentation for Project Jupyter](http://jupyter.readthedocs.io/en/latest/index.html) | [PDF](https://media.readthedocs.org/pdf/jupyter/latest/jupyter.pdf)
+- [Project Jupyter website](https://jupyter.org)

RELEASE.md

@@ -0,0 +1,48 @@
+
+Making a JupyterLab release
+===========================
+
+This document guides a contributor through creating a release of JupyterLab.
+
+Check installed tools
+---------------------
+
+Review ``CONTRIBUTING.md``. Make sure all the tools needed to generate the
+built JavaScript files are properly installed.
+
+Clean the repository
+--------------------
+
+You can remove all non-tracked files with:
+
+```bash
+git clean -xfdi
+```
+
+This would ask you for confirmation before removing all untracked files. Make
+sure the ``dist/`` folder is clean and avoid stale build from
+previous attempts.
+
+Create the release
+------------------
+
+We publish an npm package, a Python source package, and a Python universal binary wheel.  We also publish a conda package on conda-forge (see below).
+See the Python docs on [package uploading](https://packaging.python.org/distributing/#uploading-your-project-to-pypi) 
+for twine setup instructions and for why twine is the recommended method.
+
+```bash
+npm version patch
+git push origin master --tags
+npm publish
+rm -rf dist
+python setup.py sdist
+python setup.py bdist_wheel --universal
+twine upload dist/*
+md5 dist/*.tar.gz  # get the md5 hash for conda-forge install
+```
+
+Publish on conda-forge
+
+- Fork https://github.com/conda-forge/jupyterlab-feedstock
+- Create a PR with the version bump
+- Update `recipe/meta.yaml` with the new version and md5 and reset the build number to 0.