[doc] improve client doc

2 files changed, 84 insertions, 11 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()
diff --git a/docs/index.rst b/docs/index.rst
index 9e992835..679c8083 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -3,12 +3,20 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Soledad documentation
-=====================
+Soledad: synchronization of locally encrypted data among devices
+================================================================
 
-Soledad is an acronym for Synchronization of Locally Encrypted Data Among
-Devices. It is LEAP's solution for synchronizing client-encrypted data among
-all user's devices that access a LEAP provider.
+Soledad consists of a client library and a server daemon that allow
+applications to securely share a common state among devices. It is LEAP's
+solution for synchronizing client-encrypted data among user's devices that
+access a LEAP provider.
+
+
+The local application is presented with a simple, document-centric searchable
+database API. Any data saved to the database by the application is
+client-encrypted, backed up in the cloud, and synchronized among a user's
+devices. Soledad is cross-platform, open source, scalable, and features
+a highly efficient synchronization algorithm.
 
 The application is written in Python and the `source code
 <https://0xacab.org/leap/soledad>`_ is available and licensed as free software.
@@ -19,8 +27,8 @@ Both client and server are `distributed through pypi
 .. toctree::
    :maxdepth: 2
 
-   client
    server
+   client
    reference
    development
    migrations