Add basic docs for python client

Now a user can more easily find out how to update StoryBoard via the
python client.

Story: 2000710
Task: 3190

Change-Id: Ie59933344c24bca59477d75fa589a063d8866c6f

README.rst

@@ -17,5 +17,29 @@ Features
 Notes
 -----
 
-There is no command to run this; rather it can be imported into other
+This is the StoryBoard python client! It lets you interact with
-scripts.
+StoryBoard from the comfort of your own terminal! There is no
+command to run this; instead you can import it into scripts. This
+lets you perform complex actions on things in StoryBoard, eg: add an
+helpful comment on all stories with 'cannot store contact information'
+in the description, pointing users at the relevant docs, but only
+if there is no comment to this effect already. (There is an example
+of such a script in :doc:`usage`)
+
+Some sample commands are given in usage.rst. In general, most
+resources (ie: stories, tasks, projects, and so on)
+have a ``get_all()`` and ``get()`` method. The latter takes
+the resource's id as a parameter, thought it can also take
+other attributes (eg: tag name).
+
+To create a new resource, use the ``create()`` method. The
+necessary parameters depend on the resource, and if not
+documented, can be worked out from the relevant .py
+file in the code for the StoryBoard API.
+
+The ``update()`` method will update mutable fields of the resource (again,
+these vary depending on the resource).
+
+Finally, ``delete()`` will delete things.
+
+Happy task-tracking!

doc/source/usage.rst

@@ -4,4 +4,96 @@ Usage
 
 To use python-storyboardclient in a project::
 
-    TBD
+    from storyboardclient.v1 import client
+    api_url="http://storyboard-dev.openstack.org/api/v1"
+    access_token="$MY_ACCESS_TOKEN"
+    storyboard = client.Client(api_url, access_token)
+
+That will not work with storyboard-dev because of certificates, but that demos the syntax.
+
+Some sample commands to get things::
+
+    get_stories = storyboard.stories.get_all()
+    get_comments_on_one_story = storyboard.stories.get(1).comments.list()
+    get_tags_on_one_story = storyboard.stories.get(1).tags()
+    get_all_story_timeline_events = storyboard.stories.get(1).events.get_all()
+    get_worklists = storyboard.worklists.get_all()
+    get_worklists_in_board = storyboard.worklists.board_id.get(2)
+    get_due_dates = storyboard.due_dates.get_all()
+    get_due_dates_for_board = storyboard.due_dates.get_all(board_id=2)
+    get_users_in_team = storyboard.teams.get(1).users.get_all()
+    get_subscriptions = storyboard.subscriptions.get_all()
+    get_preferences_for_one_user = storyboard.users.get(1).user_preferences.get_all()
+    get_subscription_events = storyboard.subscription_events.get_all()
+    get_tokens_for_one_user = storyboard.users.get(1).user_tokens.list()
+    get_milestones = storyboard.milestones.get_all()
+    get_branches = storyboard.branches.get_all()
+    get_system_info = storyboard.system_info.get(None)
+
+
+
+
+Some sample commands to create things::
+
+
+    create_story = storyboard.stories.create(title="brand new invalid story with no tasks")
+    create_task = storyboard.tasks.create(title="new task with default settings", project_id=2, story_id=3)
+    create_branch = storyboard.branches.create(project_id=21, name='newbranch')
+    create_worklist = storyboard.worklists.create(title='new worklist', automatic=False)
+    create_board = storyboard.boards.create(title="new board", lanes='')
+
+
+
+
+Some sample commands to update things::
+
+   update_branch_title = storyboard.branches.update(id=21, name='new name')
+   update_worklist = storyboard.worklists.update(id=296, automatic=True)
+   update_board = storyboard.boards.update(id=3, title="new title")
+
+
+
+Note: there is currently no single endpoint for permissions of the form
+      api/v1/permissions. There are endpoints specific to some resources, eg:
+      api/v1/worklists/1/permissions . The python client does not support
+      these yet (patches welcome!).
+
+
+Misc example script-snippets::
+
+
+    get_stories = storyboard.stories.get_all()
+    for story in get_stories:
+        if "blah" in story.description:
+        print story
+
+    for i in range (981277, 2000690):
+        try:
+            story = storyboard.stories.get(i)
+            print story
+        except Exception as e:
+            print e
+
+Longer sample script::
+
+    from storyboardclient.v1 import client
+
+    storyboard = client.Client(api_url="http://storyboard-dev.openstack.org/api/v1", access_token="$MY_ACCESS_TOKEN")
+
+    stories = storyboard.stories.get_all()
+
+    for story in stories:
+        try:
+            if 'Cannot store contact information' in story.description and 'Friendlybot' not in story.description:
+                story.comments.create(content="This needs your gerrit preferred e-mail address to match a primary e-mail address for a foundation individual member account.\n \n If you already followed the instructions at http://docs.openstack.org/infra/manual/developers.html#account-setup - in the specified order! - and still get that, see https://ask.openstack.org/question/56720 for additional troubleshooting tips.")
+                storyboard.stories.update(id=story.id, description=story.description + '\n \n Friendlybot was here!')
+        except:
+            pass
+
+
+TODO:
+
+Some examples of `delete` commands
+Sections on updating board and worklist items need filling in.
+Timeline events for boards and worklists need adding.
+