[doc] separate api in it's own section

5 files changed, 75 insertions, 51 deletions

diff --git a/docs/api.rst b/docs/api.rst
new file mode 100644
index 00000000..9a725065
--- /dev/null
+++ b/docs/api.rst
@@ -0,0 +1,60 @@
+Soledad API
+===========
+
+.. contents::
+   :local:
+
+.. _client-side-code-api:
+
+Client-side code API
+--------------------
+
+.. autoclass:: leap.soledad.client.Soledad
+    :members:
+    :undoc-members:
+
+.. _client-side-attachments-api:
+
+Client-side attachments API
+---------------------------
+
+.. autoclass:: leap.soledad.client._document.AttachmentStates
+   :members:
+   :undoc-members:
+
+.. autointerface:: leap.soledad.client._document.IDocumentWithAttachment
+   :members:
+   :undoc-members:
+
+
+.. _server-side-attachments-rest-api:
+
+Server-side attachments REST API
+--------------------------------
+
+These are the possible ways to interact with the attachments REST API on the
+server side:
+
+===========  ================  ======== ==================
+HTTP Method  URL               Content  Possible responses
+===========  ================  ======== ==================
+GET          /user_id          -        200
+GET          /user_id/blob_id  -        200, 404
+PUT          /user_id/blob_id  The BLOB 200, 409, 507
+DELETE       /user_id/blob_id  -        200
+===========  ================  ======== ==================
+
+Server-side attachments code API
+--------------------------------
+
+.. _i-blobs-backend:
+
+.. autoclass:: leap.soledad.server.interfaces.IBlobsBackend
+   :members:
+   :undoc-members:
+
+.. _filesystem-blobs-backend:
+
+.. autoclass:: leap.soledad.server._blobs.FilesystemBlobsBackend
+   :members:
+   :undoc-members:
diff --git a/docs/attachments.rst b/docs/attachments.rst
index 31b47a70..7435eb4f 100644
--- a/docs/attachments.rst
+++ b/docs/attachments.rst
@@ -30,6 +30,8 @@ database. Encryption of data before it's sent to the server is the same used
 for Soledad documents' content during usual synchronization process (AES-256
 GCM mode).
 
+See :ref:`client-side-attachment-api` for reference.
+
 Usage example
 ^^^^^^^^^^^^^
 
@@ -69,17 +71,6 @@ the store that created it, and can put/get/delete an attachment:
         fd = yield doc.get_attachment()
         assert fd.read() == open('hackers.txt').read()
 
-API
-^^^
-
-.. autoclass:: leap.soledad.client._document.AttachmentStates
-   :members:
-   :undoc-members:
-
-.. autointerface:: leap.soledad.client._document.IDocumentWithAttachment
-   :members:
-   :undoc-members:
-
 Server-side
 -----------
 
@@ -93,6 +84,9 @@ has to be added as an HTTP auth header, as in::
 
     Authorization: Token <base64-encoded uuid:token>
 
+Check out the :ref:`server-side-attachments-rest-api` for more information on
+how to interact with the server using HTTP.
+
 The :ref:`IBlobsBackend <i-blobs-backend>` interface is provided, so in the
 future there can be different ways to store attachments in the server side
 (think of a third-party storage, for example). Currently, the
@@ -105,33 +99,3 @@ Some characteristics of the :ref:`FilesystemBlobsBackend
 * Configurable storage path.
 * Quota support.
 * Username, blob_id and user storage directory sanitization.
-
-Usage example
-^^^^^^^^^^^^^
-
-These are the possible ways to interact with the attachments REST API on the
-server side:
-
-===========  ================  ======== ==================
-HTTP Method  URL               Content  Possible responses
-===========  ================  ======== ==================
-GET          /user_id          -        200
-GET          /user_id/blob_id  -        200, 404
-PUT          /user_id/blob_id  The BLOB 200, 409, 507
-DELETE       /user_id/blob_id  -        200
-===========  ================  ======== ==================
-
-API
-^^^
-
-.. _i-blobs-backend:
-
-.. autoclass:: leap.soledad.server.interfaces.IBlobsBackend
-   :members:
-   :undoc-members:
-
-.. _filesystem-blobs-backend:
-
-.. autoclass:: leap.soledad.server._blobs.FilesystemBlobsBackend
-   :members:
-   :undoc-members:
diff --git a/docs/client.rst b/docs/client.rst
index ed813634..3befd69c 100644
--- a/docs/client.rst
+++ b/docs/client.rst
@@ -1,9 +1,9 @@
-Soledad Client API
-==================
+Soledad Client
+==============
 
-.. toctree::
-   :maxdepth: 2
+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.
 
-.. autoclass:: leap.soledad.client.Soledad
-    :members:
-    :undoc-members:
+You can also take a look at :ref:`client-side-code-api` and
+:ref:`client-side-attachments-api` for information on the API.
diff --git a/docs/index.rst b/docs/index.rst
index 6800ee42..45206b7e 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -14,8 +14,8 @@ all user's devices that access a LEAP provider.
    :maxdepth: 2
 
    client
-   attachments
    server
+   attachments
 
 Indices and tables
 ==================
diff --git a/docs/server.rst b/docs/server.rst
index 4f99f266..bec552cd 100644
--- a/docs/server.rst
+++ b/docs/server.rst
@@ -1,5 +1,5 @@
-Soledad Server documentation
-============================
+Soledad Server
+==============
 
 A U1DB server that stores data using CouchDB as its persistence layer.