Merge pull request #1102 from adamtheturtle/better-docs

Add a usage example to the 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,25 +6,99 @@ 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.
 
-Reference
----------
+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 `VWS Python Mock`_ tool:
 
-.. automodule:: vws
-   :undoc-members:
-   :members:
+.. code:: sh
+
+   pip3 install vws-python-mock
+
+.. code:: python
+
+   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())
 
-.. automodule:: vws.include_target_data
-   :undoc-members:
-   :members:
+       target_id = vws_client.add_target(
+           name=name,
+           width=1,
+           image=my_image,
+       )
+
+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.
+
+.. _VWS Python Mock: https://github.com/adamtheturtle/vws-python-mock
+
+
+Reference
+---------
 
 .. toctree::
    :maxdepth: 3
 
+   api-reference
    exceptions
    contributing
    release-process

docs/source/release-process.rst

@@ -52,7 +52,7 @@ Store your PyPI password:
 
 #. Get a GitHub access token:
 
-   Follow the `GitHub instructions <https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/>`__ for getting an access token.
+   Follow the `GitHub access token instructions`_ for getting an access token.
 
 #. Set environment variables to GitHub credentials, e.g.:
 
@@ -66,3 +66,5 @@ Store your PyPI password:
     .. code:: sh
 
        curl https://raw.githubusercontent.com/"$GITHUB_OWNER"/vws-python/master/admin/release.sh | bash
+
+.. _GitHub access token instructions: https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line/

spelling_private_dict.txt

@@ -1,14 +1,18 @@
 AuthenticationFailure
 BadImage
 ConnectionErrorPossiblyImageTooLarge
+DateRangeError
 ImageTooLarge
+InactiveProject
 MatchProcessing
 MaxNumResultsOutOfRange
 MetadataTooLarge
 ProjectInactive
+RequestQuotaReached
 RequestTimeTooSkewed
 TargetNameExist
 TargetProcessingTimeout
+TargetStatusNotSuccess
 TargetStatusProcessing
 Ubuntu
 UnknownTarget

src/vws/include_target_data.py

@@ -7,7 +7,8 @@
 
 class CloudRecoIncludeTargetData(Enum):
     """
-    Options for the ``include_target_data`` parameter of foo.
+    Options for the ``include_target_data`` parameter of
+    ``CloudRecoService.query``.
     """
 
     TOP = 'top'