started to work on the documentation (#1815)

* started to work on the documentation

* updated instructions for dev build

* Minor changes

docs/Apollo2Build.md

@@ -12,13 +12,12 @@ This guide will cover the "development mode" scenario which should be easy to st
 
 You have to install Java and the Java Development Kit (JDK) 8 or higher to run Apollo.  Both the Oracle and OpenJDK versions have been tested.
 
-### Node.js / NPM / Bower
+### Node.js / NPM
 
 You will need to [install node.js](https://nodejs.org/en/download/), which includes NPM (the node package manager) to build Apollo.
 
-Once node.js / npm is installed, install bower using (you may need sudo):
-
-    npm install -g bower 
+[nvm](https://github.com/creationix/nvm) is highly recommended for installing and managing multiple version of Node.
+Node v6 and up should work, but we recommend Node v8 or better.
 
 ### Grails / Groovy / Gradle  (optional)
 
@@ -38,12 +37,11 @@ grails for you.
 
 To setup Apollo, you can download our [latest release](https://github.com/GMOD/Apollo/releases/latest) from our [official releases](https://github.com/GMOD/Apollo/releases/) as compressed zip or tar.gz file (link at the bottom).  
 
-Alternatively you can check it out from git as directly as follows:
-
-1. git clone https://github.com/GMOD/Apollo.git Apollo
-1. cd Apollo
-1. git checkout 2.X.Y  # where X.Y is the tagged version you want from here: https://github.com/GMOD/Apollo/tags
+Alternatively you can check it out from git directly as follows:
 
+1. `git clone https://github.com/GMOD/Apollo.git Apollo`
+2. `cd Apollo`
+3. `git checkout <XYZ>` - optional, where XYZ is the tagged version you want from here: https://github.com/GMOD/Apollo/releases
 
 ### Verify install requirements
 
@@ -64,6 +62,45 @@ Also note: if there are any errors at this step, check the setup.log file for er
 Also also note: the "development mode" uses an in-memory H2 database for storing data by default. The setup guide will
 show you how to configure custom database settings.
 
+### Running the code
+
+There are several distinct parts of the code.
+
+1. Apollo client plugin (JS: [dojo](https://dojotoolkit.org/documentation/), jquery, etc.) in [client directory](../client)
+1. Server ([Grails 2.5.5](http://docs.grails.org/2.5.5/): Groovy and Java) in [grails-app](../grails-app), [src](../src), [web components](../web-app) and [tests](../test).
+1. Side-panel code / wrapper code ([GWT 2.8](http://www.gwtproject.org/doc/latest/DevGuide.html): Java).  Code is java and/or XML in [src/gwt](../src/gwt).
+1. Tools / scripts in the [examples](web_services/examples) and [tools](../tools/data): Groovy, perl, bash
+1. JBrowse (JS: [dojo](https://dojotoolkit.org/documentation/), jquery, etc.)
+
+In general, the command `./apollo run-local` will build and run the client and the server code.  Subsequent runs that do not change the GWT code can use `./apollo run-app`.  Changes to domain objects or adding controller methods may make stopping and restarting the server necessary, but most other changes will compile without having to restart the server.
+
+`./apollo test` runs the grails unit and integration [tests](../test).
+
+Updating the web-service doc can be done with `./apollo create-rest-doc`
+
+
+#### Running the code for the making client plugin changes
+
+After starting the server run `./apollo watchman` which should automatically copy any files that have been modified from the [client directory](../client) to the running instance.
+
+If for some reason this is not working then make sure that your network development tab, in your browser console, has disabled caching.  You can also run the command `gradle copy-resources-dev` manually each time instead if the files don't seem to be getting copied.
+
+#### Running the code for GWT changes 
+
+To use the GWT dev server run `gradle devmode` in a separate terminal.   This will bring up a separate [GWT dev-mode code server](http://www.gwtproject.org/doc/latest/DevGuideCompilingAndDebugging.html#dev_mode) that will compile subsequent changes to the [src/gwt](../src/gwt) code after reloading the page.  
+
+If errors seem to be a little obtuse using the dev compilation, you might try running `./apollo compile` to get more detail.
+
+#### Running the code for JBrowse changes
+
+If you are testing making changes directly to JBrowse within Apollo, the following steps should work:
+
+1. `./apollo clean-all`
+1. Clone the version of jbrowse you want into a directory called `jbrowse-download` as the root level.
+1. `./apollo run-local` to run the server
+1. In a separate terminal run `gradle copy-resources-dev` to copy over your changes to the server.
+
+
 ### Create server documentation
 
 Using an IDE like IntelliJ, NetBeans, Eclipse etc. is highly recommended in conjunction with [Grails 2.5.X documentation](http://docs.grails.org/2.5.x/).

docs/Setup.md

@@ -25,10 +25,8 @@ Other possible [build settings for JBrowse](http://gmod.org/wiki/JBrowse_Configu
      curl -sL https://deb.nodesource.com/setup_6.x | sudo -E bash -
      sudo apt-get install nodejs 
      
-NOTE: npm (installed with nodejs) must be version 2 or better.  If not installed from the above instructions, most [stable versions of node.js](https://nodejs.org/en/download/package-manager/) will supply this.  
+NOTE: npm (installed with nodejs) must be version 6 or better.  If not installed from the above instructions, most [stable versions of node.js](https://nodejs.org/en/download/package-manager/) will supply this.  [nvm](https://github.com/creationix/nvm) may also be useful.
 
-    sudo npm install -g bower 
-
 NOTE: you must link nodejs to to node if your system installs it as a ```nodejs``` binary instead of a node one.  E.g., 
 
     sudo ln -s /usr/bin/nodejs /usr/bin/node