Doc cleanup (PokemonGoF#67)

* Dockerfile dev needs git and no longer needs global grunt
* Node will use .bin apps by default; adding a watch command
* Warnings about cloud provider blocking added
* Cleans up docs by reducing duplication and just generally cleaning up the instructions
* Missing apache2 page
* Add python-dev dependency to linux install instructions; fixes PokemonGoF#74

Dockerfile.dev

@@ -33,10 +33,7 @@ WORKDIR /usr/src/app
 CMD [ "sh" ]
 
 # basic packages we're using
-RUN apk add --update ca-certificates build-base nodejs ruby ruby-dev libffi-dev
-
-# so that the npm-installed grunt can be called with just "grunt"
-RUN npm install -g grunt-cli
+RUN apk add --update ca-certificates build-base nodejs ruby ruby-dev libffi-dev git
 
 # For travis-ci
 RUN gem install travis

docs/about/contributing.rst

@@ -23,7 +23,7 @@ Titles will be shown at the top of a page and in the site nagivation. A title sh
 
 Once done editing your page, add it under one of the ``toctree`` sections in ``index.rst``.
 
-Now to previwing everything, open a terminal, go into the ``docs`` directory and use ``make html`` to generate a static copy of the documentation you can browse. Alternatively, you can run ``make auto`` and you'll get a webserver which live updates pages as you save them.
+Now to preview your changes, open a terminal, go into the ``docs`` directory and use ``make clean-auto auto``. This will start a local webserver with live updates pages as you save them.
 
 Finally, when you are finished, submit your changes as a Pull Request to be reviewed.
 

docs/about/development.rst

@@ -1,63 +1,45 @@
 App Development
-#######################
+###############
 
-.. note:: This article is about contributing to the development codebase. For contributing to the map itself see :doc:`contributing`.
+.. note::
+
+  This article is about contributing to the development codebase. For contributing to the wiki see :doc:`contributing`.
 
 .. warning::
 
-  These instructions will help you get started contributing code to the **develop** branch.
-  If you just want to **use the map** you should not use **develop**.
-  `Download a release <https://github.com/AHAAAAAAA/PokemonGo-Map/releases>`_ instead.
+  These instructions will help you get started contributing code to the ``develop`` branch. If you just want to **use the map** you should not use ``develop``, instead follow the :doc:`/basic-install/index` instructions
 
-Development requires several tools to get the job done. Python, obviously, needs to be installed. We also utilize NodeJS and Grunt for front-end tasks.
+Development requires several tools to get the job done. Python, obviously, needs to be installed. We also utilize NodeJS and Grunt for front-end asset compilation. The :doc:`/basic-install/index` instructions have an extra section about getting node installed. Follow that.
 
 Node and Grunt
-***********************
+**************
 
 Grunt is a tool to automatically run tasks against the code. We use grunt to transform the Javascript and CSS before it's run, and bundle it up for distribution.
 
 If you want to change the Javascript or CSS, you must install and run Grunt to see your changes
 
-Installing Node
-====================
-
-Download Node from the official site and install it. Version 4 or 6 will both work.
-
-https://nodejs.org/en/
-
-Installing ``grunt``
-====================
-
-After Node is installed, go into the project directory from the command-line, as usual.
-
-Then run this command
+Compiling Assets
+================
 
-``npm install -g grunt``
-
-This installs a "global" copy of grunt on your machine. You also need a local copy for the project. Run:
-
-``npm install``
+After Grunt is installed successfully, you need to run it when you change Javascript or CSS.
 
-This will install everything the ``package.json`` lists; a local copy of grunt, a lot of plug-ins, etc.
+Simply type
 
-Running ``grunt``
-===================
+.. code-block:: bash
 
-After Grunt is installed successfully, you need to run it when you change Javascript or CSS.
+  npm run watch
 
-Simply type
+on the command-line. This runs a default grunt "task" that performs a number of subtasks, like transforming JS with Babel, minifying, linting, and placing files in the right place. It will also automatically start a "watch" which will automatically rebuild files as you modify them. You can stop grunt-watch with CTRL+C.
 
-``grunt``
+If you'd like to just build assets once, you can run:
 
-on the command-line. This runs a default grunt "task" that performs a number of subtasks, like transforming JS with Babel, minifying, linting, and copying (see `Gruntfile.js <https://github.com/AHAAAAAAA/PokemonGo-Map/blob/develop/Gruntfile.js>`_)
+.. code-block:: bash
 
-grunt-watch
-====================
+  npm run build
 
-We've configured Grunt to run a "watch" task by default. Grunt will sit in the background continually re-running its tasks any time a Javascript or CSS file changes. You can leave this Watch task running while you code, to avoid the need to continually re-run Grunt every time you make a change.  You can stop grunt-watch with CTRL+C.
 
 The "/dist" directory
-***********************
+*********************
 
 Files in the "static/dist/" subdirectories should not be edited. These will be automatically overwritten by Grunt.
 

docs/advanced-install/amazon-ecs.md

@@ -1,5 +1,7 @@
 # Amazon ECS
 
+> **Warning** -- Most cloud providers have been IP blocked from accessing the API
+
 Amazon ECS is essentially managed docker allowed you to run multi-container environments easily with minimal configuration. In this guide we'll create an ECS Task that will run a single pokemongo-map container with a MariaDB container
 
 ## Requirements

docs/advanced-install/digital-ocean.md

@@ -1,6 +1,6 @@
 # DigitalOcean
 
-**Note:** There have been reports of Niantic servers blocking requests from DigitalOcean's major IP blocks (as well as Amazon AWS, and Microsoft Azure): login failures with the Error 403 are due to this. If you are experiencing this issue there is nothing we can do about it at this time.
+> **Warning** -- Most cloud providers have been IP blocked from accessing the API
 
 ## Prerequisites
 

docs/basic-install/google-maps.md

@@ -1,12 +1,8 @@
 # Google Maps Key
 
-This project uses Google Maps. There's one map coupled with the project, but as it gets more popular we'll definitely hit the rate-limit making the map unusable.
+This project uses Google Maps. Each instance of Google Maps requires an API key to make it functional. This is quick guide to setting up your own key.
 
-## Common error
-
-![Map Error](../_static/img/EOdAqUo.png)
-
-## How to fix
+## Getting the API Key
 
 1. Go to [Google API Console](https://console.developers.google.com/)
 
@@ -40,7 +36,6 @@ This project uses Google Maps. There's one map coupled with the project, but as
      - Choose Google Places API Web Service
      - Click 'ENABLE'
 
-## Configuration of API Key
+## Using the API Key
 
-1. Navigate to your pokemon map directory, and inside the config folder you will find config.ini.
-2. Add your previously created Google API key in this file, save it, and re-run the server! it should be working now! If you see an error, make sure you actually enabled the Javascript API in Step 5.
+The google maps api key may either be installed in `config/config.ini` file, or you can provide it as a command line parameter like `-k 'your key here'`

docs/basic-install/index.rst

@@ -1,55 +1,125 @@
 Basic Installation
 ##################
 
-Follow one of the guides below to get the basic pre-requisits installed:
+These instructions cover an instation from a **release** as well as from a git clone.
+
+Prerequisites
+*************
+
+Follow one of the guides below to get the basic prerequisites installed:
 
  * :doc:`osx`
  * :doc:`windows`
  * :doc:`linux`
 
-Credentials and Downloading
+Credentials
+***********
+
+ * You'll need an active Pokemon Trainer Club account or Google account
+ * Get a :doc:`google-maps`
+
+Downloading the Application
 ***************************
 
-Register either a Pokemon Club account or a Google account to use with the map. Do not use your main account.
+You have an important decision here, you may either download a "release" or use ``git`` to fetch the latest development version. The release versions tend to be more stable and require less technical install steps, but they will have fewer features.
 
-Then, download one of the following branches below:
+Release Version
+===============
+If you want to run a release version, visit the `Github releases page <https://github.com/PokemonGoMap/PokemonGo-Map/releases>`_ and download and extract the release you want to run
 
- * `Master <https://github.com/AHAAAAAAA/PokemonGo-Map/archive/master.zip>`_ (Stable Builds)
- * `Develop <https://github.com/AHAAAAAAA/PokemonGo-Map/archive/develop.zip>`_ (Active Development)
 
-The ``develop`` branch will have latest features from the development team, however it may be unstable at some times.
+``git`` Version
+===============
+
+If you're going to run a copy from the latest ``develop`` branch in ``git`` you can clone the repository:
+
+.. code-block:: bash
 
-Extract this zip file to any location.
+  git clone https://github.com/PokemonGoMap/PokemonGo-Map.git
 
 Installing Modules
 ******************
 
 At this point you should have the following:
 
-* Python 2.7
-* pip
-* nodejs
-* Unpacked archive of PokemonGo-Map
+ * Python 2.7
+ * pip
+ * PokemonGo-Map application folder
 
-Open up your shell and change to the directory of PokemonGo-Map then run the following commands:
+First, open up your shell (``cmd.exe``/``terminal.app``) and change to the directory of PokemonGo-Map.
 
-Linux:
+You can verify your installation like this:
 
 .. code-block:: bash
 
-  sudo -H pip install -r requirements.txt
-  sudo npm install -g grunt
-  npm install
-  npm run-script build
+  python --version
+  pip --version
+
+The output should look something like:
+
+.. code-block:: bash
+
+  $ python --version
+  Python 2.7.12
+  $ pip --version
+  pip 8.1.2 from /usr/local/lib/python2.7/site-packages (python 2.7)
+
+Now you can install all the Python dependencies:
 
 Windows:
 
 .. code-block:: bash
 
   pip install -r requirements.txt
-  npm install -g grunt
+
+Linux/OSX:
+
+.. code-block:: bash
+
+  sudo -H pip install -r requirements.txt
+
+``git`` Version Extra Steps
+===========================
+
+.. warning::
+
+  This only applies if you are running from a ``git clone``. If you are using a release version, skip this section
+
+In order to run from a git clone, you must compile the front-end assets with node. Make sure you have node installed for your platform:
+
+ * `Windows <https://nodejs.org/dist/v4.4.7/node-v4.4.7-x64.msi>`_
+ * `OSX <https://nodejs.org/dist/v4.4.7/node-v4.4.7.pkg>`_
+ * Linux -- refer to the `package installation <https://nodejs.org/en/download/package-manager/>`_ for your flavor of OS
+
+Once node/npm is installed, open a command window and validation your install:
+
+.. code-block:: bash
+
+  node --version
+  npm --version
+
+The output should look something like:
+
+.. code-block:: bash
+
+  $ node --version
+  v4.7.0
+  $ npm --version
+  3.8.9
+
+Once node/npm is installed, you can install the node dependencies and build the front-end assets:
+
+.. code-block:: bash
+
   npm install
-  npm run-script build
+
+  # The assets should automatically build (you'd see something about "grunt build")
+  # If that doesn't happen, you can directly run the build process:
+  npm run build
+
+
+Basic Launching
+***************
 
 Once those have run, you should be able to start using the application, like so:
 
@@ -59,7 +129,29 @@ Once those have run, you should be able to start using the application, like so:
 
 Read through the available options and set all the required CLI flags to start your own server. At a minimum you will need to provide a location, account login credentials, and a :doc:`google maps key <google-maps>`.
 
-Accessing
-*********
+The most basic config you could use would look something like this:
+
+.. code-block:: bash
+
+  python ./runserver.py -a ptc -u 'USERNAME_HERE' -p 'PASSWORD_HERE' \
+   -l 'a street address or lat/lng coords here' -st 3 -k 'maps key here'
 
 Open your browser to http://localhost:5000 and your pokemon will begin to show up! Happy hunting!
+
+Updating the Application
+************************
+
+PokemonGo-Map is a very active project and updates often. You can follow the `latest changes <https://github.com/PokemonGoMap/PokemonGo-Map/commits/develop>`_ to see what's changing.
+
+If you are running a **release** version, you can simply start this tutorial over again with a new download.
+
+If you are running a ``git`` version, you can update with a few quick commands:
+
+.. code-block:: bash
+
+  git pull
+  pip install -r requirements.txt --upgrade
+  npm install
+  npm run build
+
+You can now restart your ``runserver.py`` command.

docs/basic-install/linux.rst

@@ -3,26 +3,17 @@ Linux Install
 
 Installation will require Python 2.7 and Pip.
 
-Ubuntu
-======
+Ubuntu/Debian
+*************
 
 You can install the required packages on Ubuntu by running the following command:
 
 .. code-block:: bash
 
-  sudo apt-get install python python-pip nodejs npm
-
-Debian
-======
-
-You can install the required packages on Debian by running the following command:
-
-.. code-block:: bash
-
-  sudo apt-get install python python-pip nodejs npm nodejs-legacy
+  sudo apt-get install python python-pip python-dev
 
 Red Hat or CentOs or Fedora
-===========================
+***************************
 
 You can install required packages on Red Hat by running the following command:
 
@@ -31,4 +22,6 @@ You may also need to install the EPEL repository to install python-pip and pytho
 .. code-block:: bash
 
   yum install epel-release
-  yum install python python-pip nodejs npm python-devel
+  yum install python python-pip python-devel
+
+All set, head back to the basic install guide.