From 70a070d941a165377a0b2fd7a84bf0b443b46ea9 Mon Sep 17 00:00:00 2001
From: drebs <drebs@leap.se>
Date: Wed, 7 Jun 2017 17:44:12 -0300
Subject: [doc] separate api in it's own section
---
docs/api.rst | 60 ++++++++++++++++++++++++++++++++++++++++++++++++++++
docs/attachments.rst | 46 +++++-----------------------------------
docs/client.rst | 14 ++++++------
docs/index.rst | 2 +-
docs/server.rst | 4 ++--
5 files changed, 75 insertions(+), 51 deletions(-)
create mode 100644 docs/api.rst
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.
--
cgit v1.2.3