Refactoring: extracting methods and params.

Preparing for higher granularity singature of the functionality in the
runPermutations function by extracting many functions and breaking out
parameters.
Extracted CLI from Permutations Runner.

- Pulled all options parsing into run_swarm.py.
- Refactored runPermutations into lots of little pieces.
- Replaced runPermutations with three functions:
  - runWithConfig (accepts config dict)
  - runWithJsonFile (accepts path to JSON config file)
  - runWithPermutationsScript (accepts path to permutations.py)
- Updated run_swarms to call into permutations_runner.runWithJsonFile or
  .runWithPermutationsScript

So CLI is still entact, and new public functions exist for using the
permutations_runner directly:

- nupic.swarming.permutations_runner.runWithConfig
- nupic.swarming.permutations_runner.runWithJsonFile
- nupic.swarming.permutations_runner.runWithPermutationsScript
Removed unused imports.
Cleanup and documentation.

Doxygen docs, code cleanup.
Fixed a missing default option.
Library function returns model_params directly.

permutations_runner.runWithConfig() now returns model_params as well as
writing it to disk.
Turned outDir from arg into kwarg.
Updating deprecation warning link.
Merge branch 'run-swarm-cli' into super-hotgym
Working towards group swarming.
Defaulting outDir to cwd instead of permWorkDir.
Merge branch 'run-swarm-cli' into super-hotgym
Defaulting permWorkDir to cwd as well as outDir.
Merge branch 'run-swarm-cli' into super-hotgym
Made it through the file writing of results.