Merge pull request #38 from dynata/feature/more-docs

Updated README with more detailed usage examples and more explanation…

Author: DynataRidley

README.md

@@ -1,75 +1,108 @@
 # python-demandapi-client
 
+[![PyPI version](https://badge.fury.io/py/dynatademand.svg)](https://pypi.org/project/dynatademand/)
+
 <a href="https://github.com/dynata/python-demandapi-client/actions?query=branch%3Adev"><img alt="GitHub Actions status" src="https://github.com/dynata/python-demandapi-client/workflows/python-tests/badge.svg"></a>
 
 A Python client library for the [Dynata Demand API](https://developers.dynata.com/). There are also [go](https://github.com/researchnow/go-samplifyapi-client) and [.NET](https://github.com/researchnow/dotnet-samplifyapi-client) clients available.
 
 ## Setup
 
-The client requires environment variables to be set for the Dynata Demand API credentials. These can be found in `.env-example`.
+You can install the Demand API client with:
+
+    pip install dynatademand
+
+You can provide your Demand API credentials in a couple of ways. They can be set in the environment (a sample config is provided in `.env-example`) or you can provide them while creating the client object.
 
 ## Example Usage
 
-    demandapi = DemandAPIClient()
-    demandapi.authenticate()
-    demandapi.logout()
+```python
+# You can optionally provide your credentials here instead of environment variables.
+demandapi = DemandAPIClient("client_id", "username", "password")
+demandapi.authenticate()
+
+# Any function requiring one or more IDs should be provided as positional arguments.
+demandapi.get_project(7)
+
+# Provide query parameters as keyword-arguments.
+demandapi.get_projects(state="LAUNCHED")
+
+# Functions that send data in a request body accept a python dictionary.
+# Your data will be validated against the schemas provided in the Demand API documentation.
+project_data = {
+  'title': 'My New Survey',
+  ...
+}
+demandapi.create_project(project_data)
+```
 
 ## Supported API Functions
 
+Links to the Demand API documentation are included for each function.
+
 ### Authentication Functions
 
-authenticate()  
-refresh_access_token()  
-logout()  
+[Obtain Access Token](https://developers.dynata.com/demand-api-reference/authentication/authentication/post-token): authenticate()  
+[Refresh Access Token](https://developers.dynata.com/demand-api-reference/authentication/authentication/post-token-refresh): refresh_access_token()  
+[Logout](https://developers.dynata.com/demand-api-reference/authentication/authentication/post-logout): logout()  
 
 ### Event Functions
 
-get_event(event_id)  
-get_events(\*\*kwargs)  
+[Get Event](https://developers.dynata.com/demand-api-reference/notifications/events/get-event): get_event(event_id)  
+[Get Events](https://developers.dynata.com/demand-api-reference/notifications/events/get-events): get_events(\*\*kwargs)  
 
 ### Project Functions
 
-buy_project(project_id, buy_data)  
-close_project(project_id)  
-create_project(project_data)  
-get_project(project_id)  
-get_projects(\*\*kwargs)  
-reconcile_project(project_id, reconcile_data)  
-update_project(project_id, update_data)  
-get_project_detailed_report(project_id)  
-get_feasibility(project_id)  
-get_invoice(project_id)  
+[Buy Project](https://developers.dynata.com/demand-api-reference/core-resources/projects/post-project-buy): buy_project(project_id, buy_data)  
+[Close Project](https://developers.dynata.com/demand-api-reference/core-resources/projects/post-close-project): close_project(project_id)  
+[Create Project](https://developers.dynata.com/demand-api-reference/core-resources/projects/post-projects): create_project(project_data)  
+[Get Project](https://developers.dynata.com/demand-api-reference/core-resources/projects/get-project): get_project(project_id)  
+[Get Projects](https://developers.dynata.com/demand-api-reference/core-resources/projects/get-projects): get_projects(\*\*kwargs)  
+[Update Project](https://developers.dynata.com/demand-api-reference/core-resources/projects/post-project): update_project(project_id, update_data)  
+[Get Project Detailed Report](https://developers.dynata.com/demand-api-reference/core-resources/projects/get-project-detailed-report): get_project_detailed_report(project_id)  
+[Get Pricing & Feasibility](https://developers.dynata.com/demand-api-reference/core-resources/pricing-feasibility/get-pricing-feasibility): get_feasibility(project_id)  
+[Get Invoice PDF](https://developers.dynata.com/demand-api-reference/billing_invoicing/invoicing/get-invoices): get_invoice(project_id)  
 
 ### Line Item Functions
 
-add_line_item(project_id, lineitem_data)  
-close_line_item(project_id, line_item_id)  
-get_line_item(project_id, line_item_id)  
-get_line_items(project_id, \*\*kwargs)  
-launch_line_item(project_id, line_item_id)  
-pause_line_item(project_id, line_item_id)  
-update_line_item(project_id, line_item_id, line_item_data)  
-get_line_item_detailed_report(project_id, line_item_id)  
+[Add Line Item](https://developers.dynata.com/demand-api-reference/core-resources/lineitems/post-lineitems): add_line_item(project_id, lineitem_data)  
+[Close Line Item](https://developers.dynata.com/demand-api-reference/core-resources/lineitems/post-lineitem-close): close_line_item(project_id, line_item_id)  
+[Get Line Item](https://developers.dynata.com/demand-api-reference/core-resources/lineitems/get-lineitem): get_line_item(project_id, line_item_id)  
+[Get Line Items](https://developers.dynata.com/demand-api-reference/core-resources/lineitems/get-lineitems): get_line_items(project_id, \*\*kwargs)  
+[Launch Line Item](https://developers.dynata.com/demand-api-reference/core-resources/lineitems/post-lineitem-launch): launch_line_item(project_id, line_item_id)  
+[Pause Line Item](https://developers.dynata.com/demand-api-reference/core-resources/lineitems/post-lineitem-pause): pause_line_item(project_id, line_item_id)  
+[Update Line Item](https://developers.dynata.com/demand-api-reference/core-resources/lineitems/post-lineitem): update_line_item(project_id, line_item_id, line_item_data)  
+[Get Line Item Detailed Report](https://developers.dynata.com/demand-api-reference/core-resources/lineitems/get-detailed-line-item): get_line_item_detailed_report(project_id, line_item_id)  
 
 ### Misc Functions
 
-get_attributes(country_code, language_code, \*\*kwargs)  
-get_countries(\*\*kwargs)  
-get_sources()  
-get_survey_topics(\*\*kwargs)  
+[Get Attributes](https://developers.dynata.com/demand-api-reference/data_endpoints/attributes/get-attributes): get_attributes(country_code, language_code, \*\*kwargs)  
+[Get Countries](https://developers.dynata.com/demand-api-reference/data_endpoints/countries-languages/get-countries): get_countries(\*\*kwargs)  
+[Get Sources](https://developers.dynata.com/demand-api-reference/data_endpoints/supplier-sources/get-sources): get_sources()  
+[Get Survey Topics](https://developers.dynata.com/demand-api-reference/data_endpoints/categories/get-survey-topic): get_survey_topics(\*\*kwargs)  
 
 ## Contributing
 
 Information on [contributing](CONTRIBUTING.md).
 
 ## Testing
 
-To run the tests,
+To run the tests, you will need to install the development requirements to your environment. It's recommended to create a virtual environment for your installation to avoid any package conflicts.
+
+You can check out the code by running:
+
+    git clone https://github.com/dynata/python-demandapi-client.git
+    cd python-demandapi-client
 
+And you can create an environment by running:
+
+    # If you're using Python 2.7
     virtualenv venv
-    . venv/bin/activate
+
+    # Or if you're using Python 3:
+    python3 -m venv venv
+
+    source venv/bin/activate
     pip install -r requirements.txt
-    pytest tests
-    deactivate
 
-to run the tests for this project.
+While your virtual environment is activated, you can run `pytest tests` to run the tests.