Move usage to docs/index.

Author: paul121

README.md

@@ -6,19 +6,10 @@
 [![Twitter](https://img.shields.io/twitter/follow/farmOSorg.svg?label=%40farmOSorg&style=flat)](https://twitter.com/farmOSorg)
 [![Chat](https://img.shields.io/matrix/farmOS:matrix.org.svg)](https://riot.im/app/#/room/#farmOS:matrix.org)
 
-farmOS.py is a Python library for interacting with [farmOS](https://farmOS.org)
-over API.
+farmOS.py is a Python library for interacting with farmOS servers over API.
 
 For more information on farmOS, visit [farmOS.org](https://farmOS.org).
 
-- [Installation](#installation)
-- [Usage](#usage)
-  - [Server Info](#server-info)
-  - [Client methods](#client-methods)  
-    - [farmOS 1.x](docs/client_1x.md)
-    - [farmOS 2.x](docs/client_2x.md)
-
-
 ## Installation
 
 To install using `pip`:
@@ -29,65 +20,13 @@ $ pip install farmOS~=1.0.0b
 
 To install using `conda` see [conda-forge/farmos-feedstock](https://github.com/conda-forge/farmos-feedstock#installing-farmos)
 
-## Usage
-
-### Server Info
-
-```python
-
-info = farm_client.info()
-
-{
-  "jsonapi": {
-    "version": "1.0",
-    "meta": {
-      "links": {
-        "self": {
-          "href": "http://jsonapi.org/format/1.0/"
-        }
-      }
-    }
-  },
-  "data": [],
-  "meta": {
-    "links": {
-      "me": {
-        "meta": {
-          "id": "163c6e73-46fb-4283-b26b-153b598151ce"
-        },
-        "href": "http://localhost/api/user/user/163c6e73-46fb-4283-b26b-153b598151ce"
-      }
-    },
-    "farm": {
-      "name": "Drush Site-Install",
-      "url": "http://localhost",
-      "version": "2.x",
-      "system_of_measurement": "metric"
-    }
-  },
-  "links": {
-    "asset--animal": {
-      "href": "http://localhost/api/asset/animal"
-    },
-    "asset--equipment": {
-      "href": "http://localhost/api/asset/equipment"
-    },
-    ...
-  }
-}
-```
-
-
-### Client methods
+## Documentation
 
 farmOS.py can connect to farmOS servers running version ^1.6 or 2.x. The version should be specified when instantiating
-the farmOS client, see [Authentication](#authentication).
-
-Because of [API changes](https://2x.farmos.org/development/api/changes/) in farmOS 2.x, the client provides different
-methods depending on the server version:
+the farmOS client.
 
-- [1.x methods](docs/client_1x.md)
-- [2.x methods](docs/client_2x.md)
+- [1.x documentation](docs/client_1x.md)
+- [2.x documentation](docs/index.md)
 
 ## MAINTAINERS
 

docs/index.md

@@ -0,0 +1,88 @@
+# Introduction
+
+## Motivation
+
+farmOS.py is a Python library for interacting with farmOS servers over API.
+
+This library was developed to support more custom use cases that interact 
+with the farmOS server from a Python scripting environment. It can be used
+to build custom importers and exporters that interface with CSV, IoT and
+other APIs. farmOS.py also helps integrate with existing scientific and GIS
+tools that exist in the Python ecosystem.
+
+The [farmOS Aggregator](https://github.com/farmOS/farmOS-aggregator)
+also uses farmOS.py to communicate with farmOS servers.
+
+## Quick start
+
+Learn farmOS.py by example.
+
+### 1. Install 
+
+To install using `pip`:
+
+```bash
+$ pip install farmOS~=1.0.0b
+```
+
+To install using `conda` see [conda-forge/farmos-feedstock](https://github.com/conda-forge/farmos-feedstock#installing-farmos)
+
+### 2. Create a farm client instance
+
+```python
+from farmOS import farmOS
+
+farm_client = farmOS(
+    hostname= "https://farm.example.com",
+    client_id = "farm",
+    scope = "farm_manager",
+)
+```
+
+### 3. Authorize with farmOS server
+
+```python
+token = farm_client.authorize()
+# Complete username and password prompts.
+```
+
+### 4. Get farmOS server info
+
+```python
+info = farm_client.info()
+```
+
+### 5. CRUD Operations with a farmOS log
+
+```python
+
+# Create observation log
+observation_log = {
+    "attributes": {
+        "name": "My Great Observation",
+        "status": "pending",
+        "notes": "Some notes"       
+    } 
+}
+log = farm_client.log.send('observation', observation_log)
+log_id = log["data"]["id"]
+
+# Update the log status to "done".
+done = {
+    'id': log_id,
+    "attributes": {
+        "status": "done",
+    }
+}
+updated_log = farm_client.log.send('observation', done)
+
+# Delete the log.
+farm_client.log.delete('observation', log_id)
+```
+
+## Next steps
+
+Now that you know the basics, dive deeper into following topics:
+
+- [Authorizing with farmOS server](authorization.md)
+- [Working with farmOS resources](client_2x.md)