initial repo instructions

tutorial/repo.md

@@ -0,0 +1,41 @@
+# General Codebase Orientation
+
+The repository contains an npm package and a python package, both named `jupyterlab`.
+
+## Directories
+
+### NPM package: `src/`, `lib/`, `typings/`, `scripts/`
+
+* `src/`: the source Typescript files. `npm run build` builds the source files into javascript files in `lib/`. `npm run clean` deletes the `lib/` directory.
+* `typings/`: type definitions for external libraries that Typescript needs.
+* `scripts/`: various scripts that the npm commands invoke.
+
+### Examples: `examples/`
+
+The `examples/` directory contains a few stand-alone examples of components in the package, such as a simple notebook on a page, a console, terminal, filebrowser, etc.
+
+### Testing: `test/`
+
+The tests are stored and run in the `test/` directory. The source files are in `test/src`.
+
+### Notebook extension: `jupyterlab/`
+
+The `jupyterlab/` directory contains the Jupyter server extension. The server extension has includes a private npm package in order to build the webpack bundle the extension serves. The private npm package depends on the npm package at the root.
+
+### Git hooks: `git-hooks/`
+
+Here are some convenience git hooks that automatically rebuild the npm package and server extension every time you check out or merge in the git repo.
+
+### Documentation: `docs/`
+
+After building the docs (`npm run docs`), the `docs/index.html` is the entry point to the documentation. 
+
+## Packaging
+
+All the instructions below assume you are in the root directory of the repository.
+
+To build and install a development version of the server extension, do `pip install -e .` (this will build the npm package, build and webpack the server extension javascript, and install the appropriate links into your python environment). To enable the server extension, do `jupyter serverextension enable --sys-prefix --py jupyterlab` after installation. Then start up JupyterLab with `jupyter lab`.
+
+To rebuild the javascript for the server extension, do `npm run build:serverextension`. To have the system do this automatically after every change to the typescript source files, do `npm run watch:serverextension` and refresh your browser after each successful update.
+
+To build just the `jupyterlab` npm package, do `npm install` and then `npm run build`. To run the tests, build the npm package, then do `npm test`. To build the docs, do `npm run docs` and go to `docs/index.html`.