[docs][requirements] updating documentation + explicit reqs for pytho…

…n deps (#2213)

* [docs] updating instructions to account for python deps

* [requirements] adding pyyaml explicitly, required by android invoke task

* [docs] updating docs regarding python dependencies.

* [docs] cleanup for less confusing instructions

README.md

@@ -20,9 +20,15 @@ and development, is located under [the docs directory](docs) of the present repo
 To build the Agent you need:
  * [Go](https://golang.org/doc/install) 1.10.2 or later.
  * Python 2.7 along with development libraries.
- * [Invoke](http://www.pyinvoke.org/installing.html), you can install it via
-   `pip install invoke` or via [Homebrew](https://brew.sh) on OSX/macOS with
-   `brew install pyinvoke`.
+ * Python dependencies. You may install these with `pip install -r requirements.txt`
+   This will also pull in [Invoke](http://www.pyinvoke.org) if not yet installed.
+
+**Note:** you may want to use a python virtual environment to avoid polluting your
+      system-wide python environment with the agent build/dev dependencies.
+
+**Note:** You may have previously installed `invoke` via brew on MacOS, or `pip` in
+      any other platform. We recommend you use the version pinned in the requirements
+      file for a smooth development/build experience. 
 
 Builds and tests are orchestrated with `invoke`, type `invoke --list` on a shell
 to see the available tasks.

docs/dev/agent_dev_env.md

@@ -1,26 +1,44 @@
 # Setting up your development environment
 
-## Invoke
+## Invoke + Python Dependencies
 
-[Invoke](http://www.pyinvoke.org/installing.html) is a task runner written in
-Python that is extensively used in this project to orchestrate builds and test
+[Invoke](http://www.pyinvoke.org/) is a task runner written in Python
+that is extensively used in this project to orchestrate builds and test
 runs.
 
-The easiest way to install it on any supported platform is using `pip`:
-```
-pip install invoke
-```
+Though you may install invoke in a variety of way we suggest you use
+the provided [requirements](https://github.com/DataDog/datadog-agent/blob/master/requirements.txt)
+file and `pip`: 
 
-OSX users can install it via [Homebrew](https://brew.sh) with:
-```
-brew install pyinvoke
+```bash
+pip install -r requirements.txt
 ```
 
+This procedure ensures you not only get the correct version of invoke, but
+also any additional python dependencies our development workflow may require,
+at their expected versions. 
+It will also pull other handy development tools/deps (reno, or docker).
+
 Tasks are usually parameterized and Invoke comes with some default values that
 are used in the official build. Such values are listed in the `invoke.yaml`
 file at the root of this repo and can be overridden by setting `INVOKE_*` env
 variables (see Invoke docs for more details).
 
+
+### Note
+
+We don't want to pollute your system-wide python installation, so a python virtual
+environment is recommended (though optional). It will help keep an isolated development
+environment and ensure a clean system python.
+
+- Install the virtualenv module: 
+```pip install virtualenv```
+- Create the virtual environment: 
+```virtualenv $GOPATH/src/github.com/DataDog/datadog-agent/venv```
+- Enable the virtual environment: 
+```source $GOPATH/src/github.com/DataDog/datadog-agent/venv/bin/activate```
+
+
 ## Golang
 
 You must install [go](https://golang.org/doc/install) version 1.10.2 or above. Make

requirements.txt

@@ -3,3 +3,4 @@ invoke==1.0.0
 reno==2.9.2
 docker==3.0.1
 requests==2.19.1
+PyYAML==3.13