python: Add github-pages & update landing page docs

README.md

@@ -0,0 +1 @@
+python/README.md

python/README.md

@@ -12,66 +12,80 @@ SPDX-License-Identifier: Apache-2.0
 
 Rich Python bindings for accessing Ledger API-based applications.
 
+Documentation
+-------------
+The user documentation is available online [here](https://digital-asset.github.io/dazl-client).
+
+Installation
+------------
+If you just want to use the library, you can install it locally with `pip`:
+```sh
+pip install --user dazl
+```
+
 Requirements
 ------------
 * Python 3.6+
-* [Poetry](https://python-poetry.org/)
+* GNU Make
+* [Poetry](https://python-poetry.org/) for build/dependency management
 * [DAML SDK](https://www.daml.com)
 
 Examples
 --------
 
-All of the examples below assume you imported `dazl`.
+All of the examples below assume you imported `dazl`, and are running a ledger with the default scenario generated with `daml new`.
 
 Connect to the ledger and submit a single command:
 
 ```py
-with dazl.simple_client('http://localhost:7600', 'Alice') as client:
-    client.submit_create('Alice', 'My.Template', { someField: 'someText' })
+with dazl.simple_client('http://localhost:6865', 'Alice') as client:
+    contract = { 'issuer' : 'Alice', 'owner' : 'Alice', 'name' : 'hello world!' }
+    client.ready()
+    client.submit_create('Main.Asset', contract)
 ```
 
 Connect to the ledger as a single party, print all contracts, and close:
 
 ```py
-with dazl.simple_client('http://localhost:7600', 'Alice') as client:
+with dazl.simple_client('http://localhost:6865', 'Alice') as client:
     # wait for the ACS to be fully read
     client.ready()
     contract_dict = client.find_active('*')
 print(contract_dict)
 ```
 
-Connect to the ledger as multiple parties:
+Connect to the ledger using asynchronous callbacks:
 
 ```py
+from dazl.model.reading import ReadyEvent
 network = dazl.Network()
-network.set_config(url='http://localhost:7600')
+network.set_config(url='http://localhost:6865')
 
-alice = network.simple_party('Alice')
-bob = network.simple_party('Bob')
+alice = network.aio_party('Alice')
 
 @alice.ledger_ready()
-def set_up(event):
-    currency_cid, _ = await event.acs_find_one('My.Currency', {"currency": "USD"})
-    return dazl.create('SomethingOf.Value', {
-        'amount': 100,
-        'currency': currency_cid,
-        'from': 'Accept',
-        'to': 'Bob' })
-
-@bob.ledger_created('SomethingOf.Value')
-def on_something_of_value(event):
-    return dazl.exercise(event.cid, 'Accept', { 'message': 'Thanks!' })
-
-network.start()
+async def onReady(event: ReadyEvent):
+  contracts = await event.acs_find_one('Main.Asset')
+  print(contracts)
+
+network.run_until_complete()
 ```
 
 
 Building locally
 ----------------
+You will need to have [Poetry](https://python-poetry.org) installed, and the dependencies fetched using `poetry install`. Then do:
+
 ```sh
-make package
+make build
 ```
 
+If you see errors about incompatible python versions, switch your environment to python3 using `poetry env use python3`, for instance.
+
+Building Documentation
+----------------------
+The above command will build documentation in the root `docs/` dir. Committing this into source control and pushing to github will cause github-pages to be updated.
+
 Tests
 -----
 

python/dazl/model/reading.py

@@ -1,8 +1,58 @@
 # Copyright (c) 2019 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
 # SPDX-License-Identifier: Apache-2.0
 
+# TODO: `automodule reading` directive doesn't appear to work here, have to list each class individually.
 """
+Read-Side Types
+---------------
+
 This module contains models used on the read-side of the Ledger API.
+
+.. autoclass:: InitEvent
+  :members:
+
+.. autoclass::  InitEvent
+  :members:
+
+.. autoclass::  OffsetEvent
+  :members:
+
+.. autoclass::  ReadyEvent
+  :members:
+
+.. autoclass::  ActiveContractSetEvent
+  :members:
+
+.. autoclass::  BaseTransactionEvent
+  :members:
+
+.. autoclass::  TransactionStartEvent
+  :members:
+
+.. autoclass::  TransactionEndEvent
+  :members:
+
+.. autoclass::  ContractEvent
+  :members:
+
+.. autoclass::  ContractCreateEvent
+  :members:
+
+.. autoclass::  ContractExercisedEvent
+  :members:
+
+.. autoclass::  ContractArchiveEvent
+  :members:
+
+.. autoclass::  PackagesAddedEvent
+  :members:
+
+.. autoclass::  TransactionFilter
+  :members:
+
+.. autoclass::  EventKey
+  :members:
+
 """
 
 from dataclasses import dataclass

python/docs/index.rst

@@ -7,22 +7,22 @@ Dependencies
 ------------
 
 You will need Python 3.6 or later and a Digital Asset ledger implementation (DA Sandbox or
-DA Ledger Server). :term:`dazl` additionally requires the following libraries to be
-installed:
+DA Ledger Server). 
+
+Build-time dependencies are handled using `Poetry <https://poetry.eustace.io/>`_.
 
-* grpcio, version 1.18.0 or later
-* PyYAML
-* semver
 
 Getting Started
 ---------------
 
-This section assumes that you already have a running ledger with a DAML model loaded.
+This section assumes that you already have a running ledger with the standard `daml new` model loaded, and have imported `dazl`.
 
 Connect to the ledger and submit a single command::
 
-    with dazl.simple_client('http://localhost:7600', 'Alice') as client:
-        client.submit_create('Alice', 'My.Template', { someField: 'someText' })
+    with dazl.simple_client('http://localhost:6865', 'Alice') as client:
+        contract = { 'issuer' : 'Alice', 'owner' : 'Alice', 'name' : 'hello world!' }
+        client.ready()
+        client.submit_create('Main.Asset', contract)
 
 Connect to the ledger as a single party, print all contracts, and close::
 
@@ -32,29 +32,20 @@ Connect to the ledger as a single party, print all contracts, and close::
         contract_dict = client.find_active('*')
     print(contract_dict)
 
-Connect to the ledger as multiple parties::
+Connect to the ledger using asynchronous callbacks::
 
+    from dazl.model.reading import ReadyEvent
     network = dazl.Network()
-    network.set_config(url='http://localhost:7600')
+    network.set_config(url='http://localhost:6865')
 
-    alice = network.simple_party('Alice')
-    bob = network.simple_party('Bob')
+    alice = network.aio_party('Alice')
 
     @alice.ledger_ready()
-    def set_up(event):
-        currency_cid, _ = await event.acs_find_one('My.Currency', {"currency": "USD"})
-        return dazl.create('SomethingOf.Value', {
-            'amount': 100,
-            'currency': currency_cid,
-            'from': 'Accept',
-            'to': 'Bob' })
-
-    @bob.ledger_created('SomethingOf.Value')
-    def on_something_of_value(event):
-        return dazl.exercise(event.cid, 'Accept', { 'message': 'Thanks!' })
-
-    network.start()
+    async def onReady(event: ReadyEvent):
+      contracts = await event.acs_find_one('Main.Asset')
+      print(contracts)
 
+    network.run_until_complete()
 
 Table of Contents
 -----------------

samples/ping-pong/README.md

@@ -6,11 +6,10 @@ Ping Pong application using [DAZL](https://pypi.org/project/dazl/)
 
 Run each of the following commands in a spearate shell:
 
-* Start the sandbox and navigator via:
+* Start the sandbox and navigator on default port 6865 via:
 
       daml start
 
-* Start DAZL via
-
-      pipenv run python3 pingpong/bots.py --url {ledgerUrl}
+* Start DAZL ping-pong client via
 
+      poetry run python3 app.py --url localhost:6865