update docs (#819)

MYSQL.md

@@ -2,11 +2,15 @@
 
 ## Instructions
 
-## MacOS
+<hr>
 
-### Homebrew setup:
+### MacOS
 
-(Note: The alternative to Homebrew is [mySQL community server](https://dev.mysql.com/downloads/mysql/5.7.html#downloads) - available for all systems)
+<hr>
+
+This setup uses Homebrew. 
+
+Mojave users, please follow these instructions and, afterwards, the appended commands under [Mojave Users](#Mojave-Users) below.
 
 **Dependencies:**
 
@@ -119,13 +123,26 @@ Whenever you want to access the mysql db locally, you need to run this login fir
 $ mysql -u <username> -p
 ```
 
+### Mojave Users:
+
+- Mojave changed the location of header files necessary for compiling C extensions, as well as mySQL file locations. You'll want to run these commands to ensure that later installation runs smoothly:
+
+```Bash
+$ bundle config --local build.mysql2 "--with-ldflags=-L/usr/local/opt/openssl/lib --with-cppflags=-I/usr/local/opt/openssl/include"
+
+$ sudo installer -pkg /Library/Developer/CommandLineTools/Packages/macOS_SDK_headers_for_macOS_10.14.pkg -target /
+```
+
+<hr>
+
+### Linux
+
+<hr>
 
-## Linux
 
 **Installation:**
 
 ```Bash
-
 # If you do not have mysql-server installed run
 $ sudo apt-get install mysql-server
 # Enter a password you can rem when prompted during installation for root
@@ -161,7 +178,7 @@ $ rm -rf /etc/apparmor.d/abstractions/mysql /etc/apparmor.d/cache/usr.sbin.mysql
 $ updatedb
 $ exit
 
-````
+```
 After this repeat installation and configuration steps
 
 
@@ -169,7 +186,14 @@ Add the username and passsword on the `config/database.yml` development:
 
 Note: _You can use MariaDB in development as your database if you are more comfortable with it_
 
-## Troubleshooting
+<hr>
+
+### Troubleshooting
+
+- [MySQL build / setup](#MySQL-build-/-setup)
+- [mysql2 gem](#mysql2-gem)
+
+<hr>
 
 ### MySQL build / setup
 
@@ -190,7 +214,8 @@ Note: _You can use MariaDB in development as your database if you are more comfo
     -   Copy the contents of [`database.yml.example`](config/database.yml.example), but add your personal username and password, which should have been set up during MySQL setup.
 
 
-2. If you ever see this error, **do not update to this gem**. Look online or ask PL for help!
+2. If you ever see this error, **do not update to this gem**. Instead, try running the commands under [Mojave Users](#Mojave-Users) if you are a Mojave user, or ask look online or ask PL for help!
+
     <blockquote>
     Please install the mysql2 adapter: gem install activerecord-mysql2-adapter (cannot load such file -- mysql2/mysql2) (LoadError)
     </blockquote>

README.md

@@ -53,7 +53,118 @@ Another moving part is the new-ish Annotations 2.0 which uses [Leaflet.Illustrat
 
 ## Installation
 
-### Quick install
+Please consider which installation method you prefer. Cloud Installation requires fewer steps and is platform agnostic, but you may value working from your terminal, for familiarity, more.
+
+- [Standard Installation](#Standard-Installation)
+- [Cloud Installation](#Cloud-Installation)
+
+<hr>
+
+## Standard Installation
+
+<hr>
+
+### Prerequisites
+
+Make you have the below 3 prerequisites installed before moving forward with the [Installation Steps](#Installation-Steps).
+
+Instructions are for an Ubuntu/Debian system. Varies slightly for mac/fedora/etc.
+
+- [MySQL](#MySQL)
+- [Ruby version manager: RVM / Rbenv](#Ruby-version-manager:-RVM-/-Rbenv)
+- [Package manager: Npm and Yarn](#Package-manager:-Npm-and-Yarn)
+
+#### MySQL
+
+- MacOS and Linux users, please reference [MYSQL.md](MYSQL.md) instead.
+
+Install a database, if necessary. sqlite does not seem to work due to some table constraints:
+
+```Bash
+$ sudo apt-get install mysql-server
+```
+
+
+Application-specific dependencies:
+
+`$ sudo apt-get install bundler libmysqlclient-dev imagemagick ruby-rmagick libfreeimage3 libfreeimage-dev ruby-dev libmagickcore-dev libmagickwand-dev`
+
+(optional) For exporting, you'll need GDAL >=1.7.x (gdal.org), as well as `curl` and `zip`-- but these are not needed for much of development, unless you're working on the exporting features. 
+
+  ```Bash
+  $ sudo apt-get install gdal-bin python-gdal curl libcurl4-openssl-dev libssl-dev zip
+  ```
+
+==================
+
+
+#### Ruby version manager: RVM / Rbenv
+
+This is for RVM, but the alternative, Rbenv, also works (instructions not listed here). Don't install RVM if you already have Rbenv!
+
+Install RVM for Ruby management (http://rvm.io)
+
+```Bash
+$ curl -L https://get.rvm.io | bash -s stable
+```
+
+**Note:** At this point during the process, you may want to log out and log back in, or open a new terminal window; RVM will then properly load in your environment. 
+
+**Ubuntu users:** You may need to enable `Run command as a login shell` in Ubuntu's Terminal, under Profile Preferences > Title and Command. Then close the terminal and reopen it.
+
+Then, use RVM to install version 2.4.6 of Ruby:
+  ```Bash
+$ rvm install 2.4.6
+  ```
+
+==================
+
+#### Package manager: Npm and Yarn
+
+You'll also need **yarn** which is available through NPM. To install npm, you can run:
+  ```Bash
+$ sudo apt-get install npm
+  ```
+
+However, on Ubuntu, you may need to also install the `nodejs-legacy` package, as due to a naming collision, some versions of Ubuntu already have an unrelated package called `node`. To do this, run:
+  ```Bash
+$ sudo apt-get install nodejs-legacy
+  ```
+
+Once NPM is installed, you should be able to run:
+```Bash
+$ sudo npm install -g yarn
+```
+
+  ==================
+
+### Installation Steps
+
+You'll need Ruby v2.4.6 (use your local ruby version management system - RVM / rbenv / etc. - to install and set locally)
+
+1. Download a copy of the source with `git clone https://github.com/publiclab/mapknitter.git` 
+2. Install gems with `bundle install` from the rails root folder. You may need to run `bundle update` if you have older gems in your environment.
+3. Copy and configure config/database.yml from config/database.yml.example, using a new empty database you've created
+4. Copy and configure config/config.yml from config/config.yml.example (for now, this is only for the [Google Maps API Key, which is optional](http://stackoverflow.com/questions/2769148/whats-the-api-key-for-in-google-maps-api-v3), and a path for [logging in when running locally, also optional](#Logging-in-when-running-locally))
+5. Initialize database with `bundle exec rake db:setup`
+6. Enter ReCaptcha public and private keys in config/initializers/recaptcha.rb, copied from recaptcha.rb.example. To get keys, visit https://www.google.com/recaptcha/admin/create
+7. Install static assets (like external javascript libraries, fonts) with `yarn install` 
+8. Start rails with `bundle exec passenger start` from the Rails root and open http://localhost:3000 in a web browser. (For some, just `passenger start` will work; adding `bundle exec` ensures you're using the version of passenger you just installed with Bundler.)
+
+==================
+
+
+### Installation video
+
+For a run-through of the Prerequisites and Installation steps listed below, you can watch the install video at:
+
+http://youtu.be/iGYGpS8rZMY (may be slightly out of date, but gives an overview)
+
+<hr>
+
+## Cloud Installation
+
+<hr>
 
 We provide an install script for Codenvy's cloud service, which provides a free developer workspace server that allows anyone to contribute to a project without installing software: https://Codenvy.io.
 
@@ -77,108 +188,7 @@ $ rails server -b 0.0.0.0
 9. Hit the Play button located in the top menu bar.
 10. Open the Codenvy URL provided in the console to see MapKnitter booted up. Great work!
 
-### Installation video
+<hr>
-
-For a run-through of the Prerequisites and Installation steps listed below, you can watch the install video at:
-
-http://youtu.be/iGYGpS8rZMY (may be slightly out of date, but gives an overview)
-
-### Prerequisites
-
-Recommended; for an Ubuntu/Debian system. Varies slightly for mac/fedora/etc.
-
-#1 **MySQL**
-
-MacOS and Linux users, please reference [MYSQL.md](MYSQL.md) instead.
-
-Install a database, if necessary. sqlite does not seem to work due to some table constraints:
-
-```Bash
-sudo apt-get install mysql-server
-```
-
-
-Application-specific dependencies:
-
-`sudo apt-get install bundler libmysqlclient-dev imagemagick ruby-rmagick libfreeimage3 libfreeimage-dev ruby-dev libmagickcore-dev libmagickwand-dev`
-
-(optional) For exporting, you'll need GDAL >=1.7.x (gdal.org), as well as `curl` and `zip`-- but these are not needed for much of development, unless you're working on the exporting features. 
-
-  ```Bash
-  sudo apt-get install gdal-bin python-gdal curl libcurl4-openssl-dev libssl-dev zip
-  ```
-
-==================
-
-
-#2 **Ruby version manager** - **RVM / Rbenv**
-
-This is for RVM, but the alternative, Rbenv, also works (instructions not listed here). Don't install RVM if you already have Rbenv!
-
-Install RVM for Ruby management (http://rvm.io)
-
-```Bash
-curl -L https://get.rvm.io | bash -s stable
-```
-
-**Note:** At this point during the process, you may want to log out and log back in, or open a new terminal window; RVM will then properly load in your environment. 
-
-**Ubuntu users:** You may need to enable `Run command as a login shell` in Ubuntu's Terminal, under Profile Preferences > Title and Command. Then close the terminal and reopen it.
-
-Then, use RVM to install version 2.4.6 of Ruby:
-  ```Bash
-rvm install 2.4.6
-  ```
-
-==================
-
-#3 **Package manager - Npm and Yarn** 
-
-You'll also need **yarn** which is available through NPM. To install npm, you can run:
-  ```Bash
-  sudo apt-get install npm
-  ```
-
-However, on Ubuntu, you may need to also install the `nodejs-legacy` package, as due to a naming collision, some versions of Ubuntu already have an unrelated package called `node`. To do this, run:
-  ```Bash
-  sudo apt-get install nodejs-legacy
-  ```
-
-Once NPM is installed, you should be able to run:
-```Bash
-sudo npm install -g yarn
-```
-
-  ==================
-
-### Standard Installation
-
-You'll need Ruby v2.4.6 (use your local ruby version management system - RVM / rbenv / etc. - to install and set locally)
-
-1. Download a copy of the source with `git clone https://github.com/publiclab/mapknitter.git` 
-2. Install gems with `bundle install` from the rails root folder. You may need to run `bundle update` if you have older gems in your environment.
-3. Copy and configure config/database.yml from config/database.yml.example, using a new empty database you've created
-4. Copy and configure config/config.yml from config/config.yml.example (for now, this is only for the [Google Maps API Key, which is optional](http://stackoverflow.com/questions/2769148/whats-the-api-key-for-in-google-maps-api-v3), and a path for [logging in when running locally, also optional](#Logging-in-when-running-locally))
-5. Initialize database with `bundle exec rake db:setup`
-6. Enter ReCaptcha public and private keys in config/initializers/recaptcha.rb, copied from recaptcha.rb.example. To get keys, visit https://www.google.com/recaptcha/admin/create
-7. Install static assets (like external javascript libraries, fonts) with `yarn install` 
-8. Start rails with `bundle exec passenger start` from the Rails root and open http://localhost:3000 in a web browser. (For some, just `passenger start` will work; adding `bundle exec` ensures you're using the version of passenger you just installed with Bundler.)
-
-### Running tests
-
-When you try to run tests in MapKnitter, you can run the default Rake tasks, such as:
-
-`rake test:units`
-`rake test:functionals`
-`rake test:integration`
-
-or simply:
-
-`rake test`
-
-By running like this you'll see a lot of warnings and deprecation notices - FOR NOW -, but we're working on them. If you'd like a cleaner visual of your tests, you can just use our custom defined task:
-
-`rake test:all`
 
 ## Logging in when running locally
 
@@ -203,6 +213,21 @@ u_admin = User.create({login: 'albus', name: 'albus dumbledore', email: 'dumbled
 u_admin.role = 'admin'
 ```
 
+## Running tests
+
+When you try to run tests in MapKnitter, you can run the default Rake tasks, such as:
+
+`rake test:units` `rake test:functionals` `rake test:integration`
+
+or simply:
+
+`rake test`
+
+By running like this you'll see a lot of warnings and deprecation notices - FOR NOW -, but we're working on them. If you'd like a cleaner visual of your tests, you can just use our custom defined task:
+
+`rake test:all`
+
+
 ## Bugs and support
 
 To report bugs and request features, please use the GitHub issue tracker provided at https://github.com/publiclab/mapknitter/issues