Commit ea605179ab97431cbb887eab834b4c85acfec857

Stephen Moloney 2017-02-16T14:11:58

changes to docs

diff --git a/README.md b/README.md
index 7aaedaa..dd1ada0 100644
--- a/README.md
+++ b/README.md
@@ -2,62 +2,65 @@
 
 
 ExOvh is an helper library for the [elixir language](http://elixir-lang.org/) for the [Ovh Api](https://api.ovh.com/).
-
 To use the Openstack components of the OVH API, see [Openstex](https://github.com/stephenmoloney/openstex)
 
 
-## Project Features
+#### Project Features
 
-- Config supervised Agent running in the background which stores frequently accessed authentication information.
+- Config supervised agent running in the background which stores frequently accessed authentication information.
 - Query modules for making building requests to the [Ovh Api](https://api.ovh.com/).
-- request functions to send Queries to the [Ovh Api](https://api.ovh.com/).
+- Request functions to send Queries to the [Ovh Api](https://api.ovh.com/).
+
+
+
 
+#### Getting started - Step 1: Generating the OVH `application key`, `application secret` and `consumer key`.
 
-## Documentation
+- This may be done manually by going to `https://eu.api.ovh.com/createApp/` and following the directions outlined by `OVH` ath
+[their first steps guide](https://api.ovh.com/g934.first_step_with_api).
 
-- [See Hex Docs](https://hexdocs.pm/ex_ovh/0.1.1/api-reference.html)
+- Alternatively, this may be achieved by running a mix task. This saves me a lot of time when generating a new application.
+ [Documentation here](https://github.com/stephenmoloney/ex_ovh/blob/master/docs/mix_task.md)
 
-## Getting started
 
-#### Example (1)
+#### Getting Started - Step 2: Generating the OVH client module for your elixir application
 
-| Step 1: Generating the OVH application | Step 2: Setup |
-|---|---|
-| [Mix Task](https://github.com/stephenmoloney/ex_ovh/blob/master/docs/mix_task_basic.md) (optional) | [Setting up the Client](https://github.com/stephenmoloney/ex_ovh/blob/master/docs/getting_started_basic.md) |
+- The client module (eg `AwesomeApp.OvhClient`) is the interface for accessing the
+functions of the ***ex_ovh*** `API`.
 
-#### Example (2) - Recommended way of getting started
+- [Documentation here](https://github.com/stephenmoloney/ex_ovh/blob/master/docs/getting_started.md)
 
-| Step 1: Generating the OVH application | Step 2: Setup |
-|---|---|
-| [Mix Task](https://github.com/stephenmoloney/ex_ovh/blob/master/docs/mix_task_advanced.md) (optional) | [Setting up Clients](https://hexdocs.pm/ex_ovh/blob/master/docs/getting_started_advanced.md) |
 
+#### Usage
 
-## Usage
+- Basic examples to be added to readme.
 
-- To be added
+[See Hex Docs](https://hexdocs.pm/ex_ovh/0.2/api-reference.html)
 
 
-## Contributing
+#### Contributing
 - Pull requests welcome.
 
 
-## Tests
+#### Tests
 
 - Tests have not been written yet.
 
 
-## TODO
+#### TODO
 
 - [ ] Tests for OVH portion of library
 - [ ] Option to set the application ttl when running ovh mix task.
 - [ ] Add queries for the remainder of the OVH API. (Webstorage CDN and Cloud are the only ones covered so far)
+- [ ] Basic examples to be added to readme of usage of the api.
+- [ ] Add macro for building queries.
 
 
-## Note 
+#### Note 
 
 This is an unofficial client to the OVH api and is not maintained by OVH.
 
 
-## Licence 
+#### Licence 
 
 [MIT Licence](LICENCE.md)
\ No newline at end of file
diff --git a/docs/getting_started.md b/docs/getting_started.md
new file mode 100644
index 0000000..a5c1cd2
--- /dev/null
+++ b/docs/getting_started.md
@@ -0,0 +1,129 @@
+# Getting Started
+
+- This guide assumes your application is called `MyApp`. If your app is called something else, for example `Awesome`,
+then substitute `Awesome` for `MyApp` and `AWESOME_OVH_CLIENT_` for `MY_APP_OVH_CLIENT_` everywhere in this guide.
+
+
+#### Installation
+
+- Add `:ex_ovh` to the dependencies inx `mix.exs`.
+
+```elixir
+defp deps() do
+  [{:ex_ovh, "~> 0.1"}]
+end
+```
+
+#### `OVH` configuration
+
+- Create an OVH account at [OVH](https://www.ovh.com/us/)
+
+- Create an API application at the [OVH API page](https://eu.api.ovh.com/createApp/). Follow the
+  steps outlined by OVH there.
+
+- Add the configuration settings for the OVH application to the project `config.exs`. The following
+environment variables should be set:
+
+    - `MY_APP_OVH_CLIENT_APPLICATION_KEY`
+    - `MY_APP_OVH_CLIENT_APPLICATION_KEY`
+    - `MY_APP_OVH_CLIENT_APPLICATION_KEY`
+
+- Set them by adding them to the `.env` file. It's best not to share `.env` so run
+echo '.env' >> .gitignore` for the git repository to ensure it doesn't get added to source control.
+
+The `.env` file will be similar to as follows:
+```
+#!/usr/bin/env bash
+
+# updated on 16.2.2017
+export MY_APP_OVH_CLIENT_APPLICATION_KEY="<application_key>"
+export MY_APP_OVH_CLIENT_APPLICATION_SECRET="<application_secret>"
+export MY_APP_OVH_CLIENT_CONSUMER_KEY="<application_consumer_key>"
+```
+
+- If all of the above seems like too much work, then there is a mix task to help generate the application, see
+[mix task docs](https://github.com/stephenmoloney/ex_ovh/blob/master/docs/mix_task.md).
+
+
+#### Creating a client module
+
+***NOTE:*** Matching naming between `MyApp.OvhClient` and `MY_APP_OVH_CLIENT_APPLICATION_KEY` variables is expected.
+
+- Basic settings
+  ```elixir
+  config :my_app, MyApp.OvhClient,
+     ovh: [
+       application_key: System.get_env("MY_APP_OVH_CLIENT_APPLICATION_KEY"),
+       application_secret: System.get_env("MY_APP_OVH_CLIENT_APPLICATION_SECRET"),
+       consumer_key: System.get_env("MY_APP_OVH_CLIENT_CONSUMER_KEY"),
+     ]
+  ```
+
+- More elaborate settings
+  ```elixir
+  config :my_app, MyApp.OvhClient,
+     ovh: [
+       application_key: System.get_env("MY_APP_OVH_CLIENT_APPLICATION_KEY"),
+       application_secret: System.get_env("MY_APP_OVH_CLIENT_APPLICATION_SECRET"),
+       consumer_key: System.get_env("MY_APP_OVH_CLIENT_CONSUMER_KEY"),
+       endpoint: "ovh-eu",
+       api_version: "1.0"
+     ],
+     httpoison: [ # optional
+       connect_timeout: 20000,
+       receive_timeout: 100000
+     ]
+  ```
+
+#### Starting the `ex_ovh application`
+
+- Add `ex_ovh` to the list of applications so that it is started. Start the `ExOvh` application.
+
+```elixir
+def application do
+ [applications: [:ex_ovh]]
+end
+```
+
+
+#### Create the ovh client module
+
+
+```elixir
+defmodule MyApp.OvhClient do
+  @moduledoc :false
+  use ExOvh.Client, otp_app: :my_app, client: __MODULE__
+end
+```
+
+#### Add the client to the application supervision tree
+
+```elixir
+def start(_type, _args) do
+  import Supervisor.Spec, warn: false
+  spec1 = [supervisor(MyApp.Endpoint, [])]
+  spec2 = [supervisor(MyApp.OvhClient, [])]
+  opts = [strategy: :one_for_one, name: MyApp.Supervisor]
+  Supervisor.start_link(spec1 ++ spec2, opts)
+end
+```
+
+#### Making requests
+
+- The client `MyApp.OvhClient` is now ready.
+
+- To make requests see example usages below:
+
+
+#### Example usages
+
+- First start the application `iex -S mix`
+
+- Then try running some requests against the `API`
+
+
+
+#### Some useful requests in the `OVH console` to see applications
+
+- `GET /me/api/application` -- returns a list of application ids.
+- `GET /me/api/application/{applicationId}` -- returns json with application key.
\ No newline at end of file
diff --git a/docs/getting_started_advanced.md b/docs/getting_started_advanced.md
index 20c8922..9123584 100644
--- a/docs/getting_started_advanced.md
+++ b/docs/getting_started_advanced.md
@@ -1,4 +1,4 @@
-# Getting Started (Advanced)
+# Getting Started
 
 ## Installation 
 
diff --git a/docs/getting_started_basic.md b/docs/getting_started_basic.md
index f19a70c..2dbcb9a 100644
--- a/docs/getting_started_basic.md
+++ b/docs/getting_started_basic.md
@@ -3,7 +3,7 @@
 The basic installation is intended for use cases where only a single client is required
 on a given server.
 
-## Installation 
+#### Installation 
 
 - Add `:ex_ovh` to the dependencies.
 
@@ -13,30 +13,53 @@ defp deps() do
 end
 ```
 
-## Configuration
-
-*Note:* The configuration assumes that the environment variables such as `EX_OVH_CLIENT_ID` are already created.
+#### `OVH` Configuration
 
 - Create an OVH account at [OVH](https://www.ovh.com/us/)
 
 - Create an API application at the [OVH API page](https://eu.api.ovh.com/createApp/). Follow the
-  steps outlined by OVH there. Alternatively, there is a [mix task](https://github.com/stephenmoloney/ex_ovh/blob/master/docs/mix_task_basic.md) which can help
-  generate the OVH application.
-  
-- Add the configuration settings for the OVH application to your project `config.exs`.
+  steps outlined by OVH there.
+
+- Add the configuration settings for the OVH application to your project `config.exs`. The following
+environment variables should be set:
+
+    - `EX_OVH_APPLICATION_KEY`
+    - `EX_OVH_APPLICATION_SECRET`
+    - `EX_OVH_CONSUMER_KEY`
+
+- Set them by adding them to the `.env` file. It's best not to share `.env` so run
+echo '.env' >> .gitignore` for the git repository to ensure it doesn't get added to source control.
+
+The `.env` file will be similar to as follows:
+```
+#!/usr/bin/env bash
+
+# updated on 16.2.2017
+export MY_APP_OVH_CLIENT_APPLICATION_KEY="<application_key>"
+export MY_APP_OVH_CLIENT_APPLICATION_SECRET="<application_secret>"
+export MY_APP_OVH_CLIENT_CONSUMER_KEY="<application_consumer_key>"
+```
+
+- If all of the above seems like too much work, then there is a mix task to help generate the application, see
+[basic mix task](https://github.com/stephenmoloney/ex_ovh/blob/master/docs/mix_task_basic.md) or
+[advanced mix task](https://github.com/stephenmoloney/ex_ovh/blob/master/docs/mix_task_advanced.md)
+
+
+
+#### Some useful requests in the `OVH console` to see applications
+
+- `GET /me/api/application` -- returns a list of application ids.
+- `GET /me/api/application/{applicationId}` -- returns json with application key.
+
+
+#### Creating the appropriate `config.exs` file.
 
 ```elixir
 config :ex_ovh,
   ovh: [
-    application_key: System.get_env("EX_OVH_APPLICATION_KEY"),
-    application_secret: System.get_env("EX_OVH_APPLICATION_SECRET"),
-    consumer_key: System.get_env("EX_OVH_CONSUMER_KEY"),
-    endpoint: "ovh-eu",
-    api_version: "1.0"
-  ],
-  httpoison: [ # optional
-    connect_timeout: 20000,
-    receive_timeout: 100000
+    application_key: System.get_env("MY_APP_OVH_CLIENT_APPLICATION_KEY"),
+    application_secret: System.get_env("MY_APP_OVH_CLIENT_APPLICATION_SECRET"),
+    consumer_key: System.get_env("MY_APP_OVH_CLIENT_CONSUMER_KEY")
   ]
 ```
 
@@ -69,3 +92,11 @@ def start(_type, _args) do
 end
 ```
 
+- Now you are read to use the api, open up an `iex` console and give it a try.
+
+```
+iex -S mix
+```
+ExOvh.
+```
+
diff --git a/docs/mix_task.md b/docs/mix_task.md
new file mode 100644
index 0000000..e69de29
--- /dev/null
+++ b/docs/mix_task.md
diff --git a/lib/ex_ovh/docs/mix_task.ex b/lib/ex_ovh/docs/mix_task.ex
index fac40fe..3ef0483 100644
--- a/lib/ex_ovh/docs/mix_task.ex
+++ b/lib/ex_ovh/docs/mix_task.ex
@@ -29,17 +29,10 @@ defmodule Mix.Tasks.Ovh.Docs do
           ovh: [
             application_key: System.get_env("EX_OVH_APPLICATION_KEY"),
             application_secret: System.get_env("EX_OVH_APPLICATION_SECRET"),
-            consumer_key: System.get_env("EX_OVH_CONSUMER_KEY"),
-            endpoint: "ovh-eu",
-            api_version: "1.0"
-          ],
-          httpoison: [ # optional
-            connect_timeout: 20000,
-            receive_timeout: 100000
+            consumer_key: System.get_env("EX_OVH_CONSUMER_KEY")
           ]
 
-    See the [mix task basic](https://hexdocs.pm/ex_ovh/doc/mix_task_basic.md.html) or
-    [mix task advanced](https://hexdocs.pm/ex_ovh/doc/mix_task_advanced.md.html) for practical steps involved in running the hubic mix task.
+    See the [mix task documentation]((https://github.com/stephenmoloney/ex_ovh/blob/master/docs/mix_task.md).
     """
   end
 
diff --git a/mix.exs b/mix.exs
index 1e51d64..6205d4f 100644
--- a/mix.exs
+++ b/mix.exs
@@ -26,7 +26,8 @@ defmodule ExOvh.Mixfile do
 
   defp deps() do
     [
-      {:calendar, "~> 0.13.2"},
+#    {:calendar, "~> 0.13.2"},
+      {:calendar, "~> 0.14.0"},
       {:og, "~> 0.1"},
       {:morph, "~> 0.1.0"},
       {:poison, "~> 1.5 or ~> 2.0"},
@@ -58,8 +59,8 @@ defmodule ExOvh.Mixfile do
     [
     main: "ExOvh",
     extras: [
-             "docs/mix_task_advanced.md": [path: "mix_task_advanced.md", title: "Step 1: Generating the OVH application (Optional)"],
-             "docs/getting_started_advanced.md": [path: "getting_started_advanced.md", title: "Step 2: Setting up client(s)"]
+             "docs/mix_task.md": [path: "mix_task.md", title: "Step 1: Generating the OVH application"],
+             "docs/getting_started.md": [path: "getting_started.md", title: "Step 2: Setting up client"]
             ]
     ]
   end