documentation: re-organize doc

Change-Id: I9c2bf00dd7734889646f73db55cb475bd2cc4417

developer/jami-concepts/index.rst

+#############
+Jami Concepts
+#############
+
+Jami is a quite complex platform interacting with many different
+components and introducing many new concepts. This manual is intended
+to help you understand how Jami works, how to develop for Jami, and how
+to contribute to the project.
+
+To quickly summarize and help you to find the part of the manual that
+you are looking for, here is a brief overview of the different sections:
+
+Jami is a distributed platform that allows users to communicate without
+the need for a central server. So, a Jami account consists on a chain of
+certificate (CA, Account, Device) that is used to authenticate the user
+and to encrypt the communication. The account is stored on the user's
+device, not on a server.
+
+For this, here is the page that explains how it works:
++ :ref:`account-management`
++ :ref:`jami-identifiers`
+
+After the user account is created, the user can contact other people by
+sending connection requests through a DHT (https://opendht.net) after finding the contact id
+(directly known or by lookup the name server). If both parties
+agree, they will first try to create a p2p TCP link (with the ICE protocol), then
+encrypt it via TLS and use it as a multiplexed socket to transmit data for various
+protocols c.f.:
+
++ :ref:`contact-management`
++ :ref:`banned-contacts`
++ :ref:`connection-manager`
++ :ref:`name-server-protocol`
+
+When both peers are in their contact list, a conversation is created. This conversation
+is called a **Swarm**. A **swarm** is synced between all devices in a conversation via
+the `git` protocol (it's a git repository) and connections across devices in a conversation
+are routed by a component called the **drt** (distributed routing table).
+
++ :ref:`swarm`
++ :ref:`drt`
+
+Then, the connection can be used to send messages, files, or to make calls (1:1 or conferences).
+
++ :ref:`calls`
++ :ref:`calls-in-swarm`
++ :ref:`file-transfer`
++ :ref:`conference-protocol`
+
+.. note::
+   Calls may be fully replaced by call in swarms in the future (except for SIP accounts)
+
+Finally, a user can have multiple devices and a lot of information is synced between them.
+
++ :ref:`synchronizing-profiles`
++ :ref:`synchronization-protocol`
+
+.. toctree::
+   :maxdepth: 1
+
+   account-management
+   banned-contacts
+   calls-in-swarm
+   calls
+   conference-protocol
+   connection-manager
+   contact-management
+   drt
+   file-transfer
+   jami-identifiers
+   name-server-protocol
+   swarm
+   synchronization-protocol
+   synchronizing-profiles

developer/swarm.md → developer/jami-concepts/swarm.md

@@ -61,7 +61,12 @@ We identified four modes for swarm chat that we want to implement:
 
 Sending a message is pretty simple. Alice writes a commit-message in the following format:
 
-**TODO format unclear**
+```json
+{
+    "type": "text/plain",
+    "body": "coucou"
+}
+```
 
 and adds her device and CRL to the repository if missing (others must be able to verify the commit). Merge conflicts are avoided because we are mostly based on commit messages, not files (unless CRLS + certificates but they are located). then she announces the new commit via the **DRT** with a service message (explained later) and pings the DHT for mobile devices (they must receive a push notification).
 
@@ -74,14 +79,14 @@ For pinging other devices, the sender sends to other members a SIP message with
 1. *Bob* do a git pull on *Alice*
 2. Commits MUST be verified via a hook
 3. If all commits are valid, commits are stored and displayed. Then *Bob* announces the message via the DRT for other devices.
-4. If all commits are not valid, pull is canceled. *Alice* must reestablish her state to a correct state. **TODO process*
+4. If all commits are not valid, pull is canceled. *Alice* must reestablish her state to a correct state.
 
 ### Validating a commit
 
 To avoid users pushing some unwanted commits (with conflicts, false messages, etc), this is how each commit (from the oldest to the newest one) MUST be validated before merging a remote branch:
 
 Note: if the validation fails, the fetch is ignored and we do not merge the branch (and remove the data), and the user should be notified
-Note2: If a fetch is too big, it's not done (**TODO**)
+Note2: If a fetch is too big, it's not merged
 
 + For each commits, check that the device that tries to send the commit is authorized at this moment and that the certificates are present (in /devices for the device, and in /members or /admins for the issuer).
 + 3 cases. The commit has 2 parents, so it's a merge, nothing more to validate here
@@ -422,8 +427,6 @@ In case of failure, when a device of the conversation will be back online, we wi
 
 ### Call in swarm
 
-#### TODO: nameserver part
-
 #### Idea
 
 A swarm conversation can have multiple rendez-vous. A rendez-vous is defined by the following uri:
@@ -613,7 +616,7 @@ Note: Following notes are not organized yet. Just some line of thoughts.
 
 For a serious group chat feature, we also need serious crypto. With the current design, if a certificate is stolen as the previous DHT values of a conversation, the conversation can be decrypted. Maybe we need to go to something like **Double ratchet**.
 
-Note: a lib might exist to implement group conversations. TODO, investigate.
+Note: a lib might exist to implement group conversations.
 
 Needs ECC support in OpenDHT
 

developer/apis-of-jami.md → developer/new-developers/apis-of-jami.md

@@ -39,3 +39,8 @@ All the documentation and code for the REST API is located in `jami-daemon/bin/r
 ### Python wrapper
 
 A Python wrapper is available in `jami-daemon/tools/jamictrl`. This wrapper uses DBus.
+
+## Plugins
+
+Plugins are a good way to customize Jami if you want to interact with streams (Audio, Video or chat). Several plugins are already available
+through the Plugin Store (in the settings of your Jami application).
\ No newline at end of file

developer/new-developers/index.rst

+##############
+New Developers
+##############
+
+This part of the documentation is intended for new developers who want to
+contribute to the project. It explains the tools, some conventions and some
+tools.
+
+.. toctree::
+   :maxdepth: 1
+
+   apis-of-jami
+   coding-style
+   debugging-tools
+   improving-quality-of-jami
+   qt-qml-coding-style
+   qt-qml-testing-tools
+   submitting-your-first-patch
+   working-with-gerrit
\ No newline at end of file