Progress towards usage documentation

Author: adamtheturtle

README.rst

@@ -24,8 +24,19 @@ Getting Started
 
    from vws import VWS, CloudRecoService
 
-   vws_client = VWS(server_access_key='...', server_secret_key='...')
-   cloud_reco_client = CloudRecoService(client_access_key='...', client_secret_key='...')
+   server_access_key = '[server-access-key]'
+   server_secret_key = '[server-secret-key]'
+   client_access_key = '[client-access-key]'
+   client_secret_key = '[client-secret-key]'
+
+   vws_client = VWS(
+       server_access_key=server_access_key,
+       server_secret_key=server_secret_key,
+   )
+   cloud_reco_client = CloudRecoService(
+       client_access_key=client_access_key,
+       client_secret_key=client_secret_key,
+   )
    name = 'my_image_name'
 
    with open('/path/to/image.png', 'rb') as my_image_file:

docs/source/api-reference.rst

@@ -0,0 +1,10 @@
+API Reference
+=============
+
+.. automodule:: vws
+   :undoc-members:
+   :members:
+
+.. automodule:: vws.include_target_data
+   :undoc-members:
+   :members:

docs/source/index.rst

@@ -6,38 +6,94 @@ Installation
 
 .. code:: sh
 
-   pip install vws-python
+   pip3 install vws-python
 
 This is tested on Python 3.7+.
 Get in touch with ``[email protected]`` if you would like to use this with another language.
 
-Example usage
--------------
+Usage
+-----
 
 See the :doc:`api-reference` for full usage details.
 
 .. code:: python
 
+   import io
+
+   from vws import VWS, CloudRecoService
+
+   server_access_key = '[server-access-key]'
+   server_secret_key = '[server-secret-key]'
+   client_access_key = '[client-access-key]'
+   client_secret_key = '[client-secret-key]'
+
+   vws_client = VWS(
+       server_access_key=server_access_key,
+       server_secret_key=server_secret_key,
+   )
+   cloud_reco_client = CloudRecoService(
+       client_access_key=client_access_key,
+       client_secret_key=client_secret_key,
+   )
+   name = 'my_image_name'
+
+   with open('/path/to/image.png', 'rb') as my_image_file:
+      my_image = io.BytesIO(my_image_file.read())
+
+   target_id = vws_client.add_target(
+       name=name,
+       width=1,
+       image=my_image,
+   )
+   vws_client.wait_for_target_processed(target_id=target_id)
+   matching_targets = cloud_reco_client.query(image=my_image)
+
+   assert matching_targets[0]['target_id'] == target_id
+
 Testing
 -------
 
-To write unit tests for code which uses this library, without using your Vuforia quota, you can use the https://github.com/adamtheturtle/vws-python-mock tool:
+To write unit tests for code which uses this library, without using your Vuforia quota, you can use the `VWS Python Mock`_ tool:
 
-XXX example
+.. code:: sh
 
-There are some differences... see XXX for details
+   pip3 install vws-python-mock
 
+.. code:: python
 
-Reference
----------
+   from mock_vws import MockVWS, VuforiaDatabase
+
+   with MockVWS() as mock:
+       database = VuforiaDatabase()
+       mock.add_database(database=database)
+       vws_client = VWS(
+           server_access_key=server_access_key,
+           server_secret_key=server_secret_key,
+       )
+       cloud_reco_client = CloudRecoService(
+           client_access_key=client_access_key,
+           client_secret_key=client_secret_key,
+       )
+
+       name = 'my_image_name'
+
+       with open('/path/to/image.png', 'rb') as my_image_file:
+           my_image = io.BytesIO(my_image_file.read())
+
+       target_id = vws_client.add_target(
+           name=name,
+           width=1,
+           image=my_image,
+       )
 
-.. automodule:: vws
-   :undoc-members:
-   :members:
+There are some differences between the mock and the real Vuforia.
+See https://vws-python-mock.readthedocs.io/en/latest/differences-to-vws.html for details.
 
-.. automodule:: vws.include_target_data
-   :undoc-members:
-   :members:
+.. _VWS Python Mock: https://github.com/adamtheturtle/vws-python-mock
+
+
+Reference
+---------
 
 .. toctree::
    :maxdepth: 3