[#18] - Add documentation

README.md

@@ -1,14 +1,12 @@
 
-![Logo](readme-assets/logo.png)
-
-# Demo Bootstrap
+<div style="text-align:center"><img src="readme-assets/logo.png"></div>
+<!--![Logo](readme-assets/logo.png)-->
 
 [![Build Status](https://img.shields.io/travis/ZacBlanco/hdp-demo-bootstrap.svg?branch=master)](https://travis-ci.org/ZacBlanco/hdp-demo-bootstrap) [![Coverage Status](https://coveralls.io/repos/github/ZacBlanco/hdp-demo-bootstrap/badge.svg?branch=master)](https://coveralls.io/github/ZacBlanco/hdp-demo-bootstrap?branch=master) [![Python 2.6, 2.7](https://img.shields.io/badge/python-2.6%2C%202.7-orange.svg)](https://docs.python.org/2/) [![Hortonworks Data Platform](https://img.shields.io/badge/Hortonworks-Data%20Platform-brightgreen.svg)](http://hortonworks.com)
 
+# Demo Bootstrap
 
-> An easy to use framemwork for creating, installing, and running end-to-end applications on HDP.
-
-------------------------------
+> An easy to use framemwork for creating, installing, and running end-to-end demo applications on the Hortonworks Data Platform.
 
 This framework hopes to provide a rich set of features including the following:
 
@@ -25,4 +23,7 @@ This framework hopes to provide a rich set of features including the following:
 
 \* = possible feature
 
-------------------------------------
+
+### Need more Information?
+
+[Read the docs here!](docs/README.md)

docs/README.md

@@ -1,7 +1,5 @@
 
 # HDP Demo Bootstrap
-
-----------------------
 
 
 ## Module Documentation
@@ -11,9 +9,10 @@ Below is an index which provides the documentation for each python module.
 
 ### List of Modules
 
-- [`ambari.py`](ambari.md)
-- [`config.py`](config.md)
-- [`curl_client.py`](curl_client.md)
-- [`generator.py`](generator.md)
-- [`service_installer.py`](service_installer.md)
-- [`shell.py`](shell.md)
+- [ambari.py](ambari.md)
+- [config.py](config.md)
+- [curl_client.py](curl_client.md)
+- [generator.py](generator.md)
+- [service_installer.py](service_installer.md)
+- [shell.py](shell.md)
+

docs/ambari.md

@@ -0,0 +1,90 @@
+[Back to Index](README.md)
+
+# Ambari
+
+`ambari.py` is a module that houses the `Ambari` class. This class can make remote calls to an instance of the Ambari REST API.
+
+This module utilizes [`curl_client.py`](curl_client.md) in order to make the RESTful API calls to an Ambari instance.
+
+In its current state there is not much functionality, but more calls can be made possible by using the underlying [`curl_client`](curl_client.md) module to make REST calls to the API if the current features are not enough
+
+--------
+
+## Methods
+
+### `Ambari.__init__(username='', password='', proto='http', server='127.0.0.1', port=8080)`
+
+The Ambari client can take anywhere between 0 and 5 different arguments:
+
+- username - (username to login to Ambari)
+- password - (password to login to Ambari)
+- proto - (The protocol used by Ambari Server. Must be one of: 'http' or 'https')
+- server - (The IP address or hostname of the Ambari server)
+- port - (The port on which ambari server is running)
+
+The defaults for each of the above are shown in the argument list.
+
+
+### `Ambari.getClusters(query='')`
+
+Makes RESTful API call to `GET /api/v1/clusters`
+
+Returns a piece of JSON via `json.loads` from the API.
+
+If an error occurred when making the call to Ambari the error message from the curl client will be returned in the following format:
+
+	{
+		"message": error_message_string
+	}
+
+### `Ambari.getServices(cluster_name, query='')`
+
+
+Makes RESTful API call to `GET /api/v1/clusters/{CLUSTER_NAME}/services`
+
+Returns a piece of JSON via `json.loads` from the API.
+
+If an error occurred when making the call to Ambari the error message from the curl client will be returned in the following format:
+
+	{
+		"message": error_message_string
+	}
+
+
+### `Ambari.getClusterInfo(cluster_name, query='')`
+
+Makes RESTful API call to `GET /api/v1/clusters/{CLUSTER_NAME}`
+
+Returns a piece of JSON via `json.loads` from the API.
+
+If an error occurred when making the call to Ambari the error message from the curl client will be returned in the following format:
+
+	{
+		"message": error_message_string
+	}
+
+### `Ambari.set_username(user)`
+
+Updates the the desired username to make REST calls to Ambari
+
+### `Ambari.set_password(password)`
+
+Updates the the desired password to make REST calls to Ambari
+
+**NOTE:** This should _not_ be used in a secure environment. Sensitive passwords should not be used nor stored here. This framework is designed for **test environments only**
+
+### `Ambari.set_proto(proto)`
+
+Updates the the desired protocol to make REST calls to Ambari. The only values allowed are '`http`' and '`https`'
+
+### `Ambari.set_server(server)`
+
+Updates the the desired ambari server hostname/IP Address to make REST calls to Ambari.
+
+### `Ambari.set_port(port)`
+
+Updates the desired port on which Ambari is running. **Must be an integer**.
+
+
+
+

docs/config.md

@@ -0,0 +1,42 @@
+[Back to Index](README.md)
+
+# Config
+
+`config.py` is a module which contains some methods to make reading configuration files easy.
+
+--------
+
+## Methods
+
+### `Ambari.read_config(config_file)`
+
+This method retrieves and reads a configuration file `conf` directory and returns an embedded dictionary object where all of the key-value pairs are stored
+
+[See more on the configuration file format in the python docs](https://docs.python.org/2/library/configparser.html)
+
+A typical configuration file has the following format:
+
+	[SECTION HEADER 1]
+	key1=value1
+	key2=value2
+
+	[SECTION HEADER 2]
+	key3=value3
+	key4=value4
+
+	....
+
+Using the `read_config` method you can use the object to access the values via the section header and then the key name
+
+Example:
+
+	conf = config.read_config(filename)
+
+	conf['SECTION HEADER 1']['key1'] # Now holds value1
+	conf['SECTION HEADER 2']['key4'] # Now holds value4
+
+### `config.get_conf_dir()`
+
+This method will search for a directory named `conf` in the local directory structure. It will return the path to this directory. 
+
+The method is used when searching for a configuration file in the `read_config` method. However, it may be used outside of the `config` module if other modules utilize the `conf` directory.

docs/curl_client.md

@@ -0,0 +1,103 @@
+[Back to Index](README.md)
+
+# CurlClient
+
+`curl_client.py` is a module that houses the `CurlClient` class. This class utilizes the `shell.py` module in order to build `curl` commands to make HTTP requests.
+
+## Usage
+
+Sample Usage:
+
+	from curl_client import CurlClient
+	client = CurlClient(username, password, protocol, server, port)
+
+	client.make_request('GET', '/api/v1/clusters', '-k', '')
+
+
+## Methods
+
+### `CurlClient.__init__(username='', password='', proto='http', server='127.0.0.1', port=8080)`
+
+Initializes the CurlClient object. 
+
+Defaults:
+
+| Parameter | Value | 
+|-----------|-------|
+| `proto`   |`http` |
+| `server`  |`127.0.0.1`|
+| `port`    | `8080`|
+
+These parameters are used in all requests made by the CurlClient
+
+### `CurlClient.make_request(verb, request, options='', query='')`
+
+Returns a two item array of the command output. One element for `std_out` and another element for `std_err` which is propagated from the `shell.py` module. The first element in `std_out` where the second element is `std_err`
+
+	[std_out, std_err]
+	output[0] = std_out
+	output[1] = std_err
+
+##### Required parameters:
+
+- verb
+- request
+
+`verb` is one of the four basic HTTP verbs. It must be one of: 
+
+- GET
+- PUT
+- POST
+- DELETE
+
+`request` is the path to which you want to make your request.
+
+Given a server with an API endpoint at `http://127.0.0.1:8080` with a a `request` parameter of `/request/path`
+
+The curl call made might look something like
+
+	curl -u username:password -X GET http://127.0.0.1:8080/request/path
+
+The value of `request` is simply appended to the address of the server.
+
+##### Optional Parameters
+
+- options
+- query
+
+`options` allows you to add more command line options to the curl request. You can add things like `-k` or `-i` if desired for the testing environment
+
+`query` allows you to add query parameters to the HTTP requests at the end of the url. 
+
+Example:
+
+- `query = fields=tasks/Tasks`
+
+	curl -u username:password -X GET http://127.0.0.1:8080/request/path?fields=tasks/Tasks
+
+
+### `CurlClient.set_username(user)`
+
+Updates the the desired username to make REST calls to web server. (May be left empty if not needed)
+
+### `CurlClient.set_password(password)`
+
+Updates the the desired password to make REST calls to web server. (May be left empty if not needed)
+
+**NOTE:** This should _not_ be used in a secure environment. Sensitive passwords should not be used nor stored here. This framework is designed for **test environments only**
+
+### `CurlClient.set_proto(proto)`
+
+Updates the the desired protocol to make REST calls to the web service. The only values allowed are '`http`' and '`https`'
+
+### `CurlClient.set_server(server)`
+
+Updates the the desired server hostname/IP Address of the location of web server.
+
+### `CurlClient.set_port(port)`
+
+Updates the desired port on which web server is running. **Must be an integer**.
+
+
+
+

docs/generator.md

@@ -1,3 +1,5 @@
+[Back to Index](README.md)
+
 # Generator
 
 `generator.py` is a module which contains the `DataGenerator()` class. It is used in conjunction with an implementation of an Exporter and a JSON schema in order to generator random datasets.
@@ -23,6 +25,20 @@ This should be an implementation of the Exporter superclass. This is necessary t
 
 This is the seed for the random number generator. It is entirely optional and if the seed given is found to be a zero-length string then the seed used will be pseudo-randomly generated.
 
+### `generator.generate()`
+
+The `generate()` method takes no arguments and will produce a single line (entry) of data given the schema provided during instantiation.
+
+The data produced will be in the format:
+
+	{
+		"field_name_1": field_value_1,
+		"field_name_2": field_value_2,
+		"field_name_3": field_value_3,
+		....
+	}
+
+
 ## Generator Configuration Reference
 
 The data generator is driven by a JSON configuration. Each field for a generator row is driven by this configuration.