Merge branch 'docs-content' of 'https://github.com/VSevagen/grimoirel…

…ab-sortinghat'

Merges #576
Closes #576

docs/index.rst

@@ -11,5 +11,15 @@ A tool to manage identities.
 .. toctree::
    :maxdepth: 1
    :caption: SortingHat:
-   
+
    What is SortingHat ? <sortinghat/index.md>
+   Profile and identities <sortinghat/profile.md>
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Developer Documentation:
+
+   SortingHat's Database <sortinghat/database.md>
+   Install SortingHat (Backend and Frontend) <https://github.com/chaoss/grimoirelab-sortinghat/blob/muggle/README.md#requirements>
+   Install SortingHat as a Service <https://github.com/chaoss/grimoirelab-sortinghat/blob/muggle/README.md#sortinghat-service>
+   API reference doc <sortinghat/api-reference.rst>

docs/sortinghat/api-reference.rst

@@ -0,0 +1,5 @@
+API reference doc
+=================
+
+* :ref:`genindex`
+* :ref:`modindex`

docs/sortinghat/database.md

@@ -1,7 +1,16 @@
 # How is data stored in SortingHat
 
-SortingHat maintains an SQL database with the identities coming from different sources. Identities corresponding to the same person can be merged into the same <code>individual</code>, with a unique uuid. For each individual, a profile can be defined, with the name and other data to show corresponding person by default.
+SortingHat maintains an SQL database with the identities coming from different sources.
+Identities corresponding to the same person can be merged into the same individual, with a
+unique uuid. For each individual, a profile can be defined, with the name and other data
+to show corresponding person by default.
 
-The conceptual schema of the SortingHat database is shown below. Individuals are the first-class citizens. They have a profile, which summarizes the member data, and can be linked to more than one identity and organization, which are automatically extracted from the software development tools of your project. Note that organizations or identities can be easily excluded from SortingHat by registering their names/emails/usernames to a matching blacklist. The filter associated to the blacklist is executed every time an identity is inserted to the database or modified.
+The conceptual schema of the SortingHat database is shown below. Individuals are the
+first-class citizens. They have a profile, which summarizes the member data, and can be
+linked to more than one identity and organization, which are automatically extracted from
+the software development tools of your project. Note that organizations or identities can
+be easily excluded from SortingHat by registering their names/emails/usernames to a
+matching blacklist. The filter associated to the blacklist is executed every time an
+identity is inserted to the database or modified.
 
-![sh-database-diagram](./sh-database-diagram.svg)
+![sh-database-diagram](./assets/sh-database-diagram.svg)

docs/sortinghat/index.md

@@ -1,5 +1,12 @@
 # Contributor Information Management using SortingHat
 
-[SortingHat](https://github.com/chaoss/grimoirelab-sortinghat/tree/muggle) is a part of the GrimoireLab toolset and is used to gather data related to contributor information. Data about each individual is stored as a unique profile which may or may not include several identities belonging to the same contributor. Moreover each individual can be affiliated with a particular organisation where the latter was employed.
+[SortingHat](https://github.com/chaoss/grimoirelab-sortinghat/tree/muggle) is a part of
+the GrimoireLab toolset and is used to gather data related to contributor information.
+Data about each individual is stored as a unique profile which may or may not include
+several identities belonging to the same contributor. Moreover each individual can be
+affiliated with a particular organisation where the latter was employed.
 
-SortingHat is currently being converted into a service so the documentation at the <strong>[master](https://github.com/chaoss/grimoirelab-sortinghat)</strong> branch would be totally inaccurate. The on-going development is carried out at the <strong>[muggle](https://github.com/chaoss/grimoirelab-sortinghat/tree/muggle)</strong> branch.
+SortingHat is currently being converted into a service so the documentation at the
+**[master](https://github.com/chaoss/grimoirelab-sortinghat)** branch would be totally
+inaccurate. The on-going development is carried out at the
+**[muggle](https://github.com/chaoss/grimoirelab-sortinghat/tree/muggle)** branch.

docs/sortinghat/profile.md

@@ -0,0 +1,33 @@
+# Difference between profiles and identities
+
+Each individual will have a unique profile which may or may not consists of several
+identities. A profile is unique to one particular individual, that is no-one will have the
+same profile with the same information (Name, Email, Username, Affiliations etc... )
+
+For example, you can think of **profiles as human beings**. Every human being is
+different, hence unique. If that person goes to the bank and creates an account, he'll be
+given an account card. That is one of his identities, a customer of the bank.
+
+![profiles](./assets/profiles.png)
+
+The above image further explains the difference between profiles and identities.
+
+As you can see, there is a single individual and that individual has several identities
+which are listed below
+
+- **Git**<br>
+  Usernames: John Doe, John M. Doe
+
+  Emails: jdoe@example.com, jmdoe@gmail.examle.com, jdoe@gmail.example.com
+
+- **Github**<br>
+  Username: johndoe
+
+- **Mailman**<br>
+  Emails: jdoe@gmail.example.com, jdoe@example.com, mail@jdoe.es
+
+- **Phabricator**<br>
+  Email: jdoe@example.com
+
+- **Slack**<br>
+  Username: jdoe