[doc] improve client doc

1 files changed, 70 insertions, 5 deletions

diff --git a/docs/client.rst b/docs/client.rst
index 3befd69c..bbbc1dec 100644
--- a/docs/client.rst
+++ b/docs/client.rst
@@ -1,9 +1,74 @@
 Soledad Client
 ==============
 
-Current reasoning about Soledad can be found `here
-<https://leap.se/en/docs/design/soledad>`_. That will be cleaned up and
-migrated here in the future.
+The Soledad Client is a Python library aimed to provide access to a document
+store that can be synchronized securelly with other deviced through the Soledad
+Server. Key aspects of Soledad Client include:
 
-You can also take a look at :ref:`client-side-code-api` and
-:ref:`client-side-attachments-api` for information on the API.
+  * **Encrypted local storage:** All data cached locally is stored in an
+    encrypted database.
+
+  * **Client-side encrypted sync:** Soledad puts very little trust in the
+    server by encrypting all data before it is synchronized to the server and
+    by limiting ways in which the server can modify the user's data.
+
+  * **Document database:** An application using the Soledad client library is
+    presented with a document-centric database API for storage and sync.
+    Documents may be indexed, searched, and versioned.
+
+  * **Blobs storage:** The client and server API provide blobs storage, which
+    can be used both for data delivery in the server side (i.e. email) and
+    payload storage on the client side.
+
+Setting-up
+----------
+
+The following information is needed in order to instantiate a soledad client:
+
+  * ``uuid``: the user's uuid.
+  * ``passphrase``: the user's passphrase.
+  * ``secrets_path``: a local path for secrets storage.
+  * ``local_db_path``: a local path for the documents database.
+  * ``server_url``: the Soledad Server's URL.
+  * ``cert_file``: a local path for the CA certificate.
+  * ``auth_token``: an authentication token obtained after logging into the
+    provider.
+
+Once all pieces are in place, you can instantiate the client as following:
+
+.. code-block:: python
+
+    from leap.soledad.client import Soledad
+    client = Soledad(
+        uuid,
+        passphrase,
+        secrets_path=secrets_path,
+        local_db_path=local_db_path,
+        server_url=server_url,
+        cert_file=cert_file,
+        auth_token=token)
+
+Usage example
+-------------
+
+Soledad is written in the `Twisted asynchronous model
+<https://twistedmatrix.com/documents/current/core/howto/defer-intro.html>`_, so
+you will need to make sure a `reactor
+<http://twistedmatrix.com/documents/current/core/howto/reactor-basics.html>`_
+is running.
+
+Creation of a document and synchronization is done as follows:
+
+.. code-block:: python
+
+    yield client.create_doc({'my': 'doc'}, doc_id='some-id')
+    doc = yield client.get_doc('some-id')
+    yield client.sync()
+
+The document can be modified and synchronized again:
+
+.. code-block:: python
+
+    doc.content = {'new': 'content'}
+    yield client.put_doc(doc)
+    yield client.sync()