Add documentation of results structure

docs/index.rst

@@ -16,4 +16,5 @@ Welcome to PSOT - protein sequence observation tool's documentation!
    modules
    profiles
    repositories
+   results_format
 

docs/results_format.rst

+Result documents
+=============
+.. highlight:: json
+
+The result JSON documents have the following structure::
+
+	{
+	   "id" : "seq_10.cds_1", # query id
+	   "computations" : [     # list of computation results
+		  {					  # each computation is an object
+			 "tool" : {       # consisting of tool information
+				"name" : "hmmscan",
+				"database" : "/db/pfam/Pfam-A.hmm",
+				"version" : "3.1b2"
+			 },
+			 "results" : []   # and a list of results
+		  },
+		  {
+			 "results" : [
+				{             # each result is an object
+				   "signalpeptide" : false
+				}
+			 ],
+			 "tool" : {
+				"name" : "SignalP",
+				"mode" : "euk",
+				"version" : "4.1"
+			 }
+		  }
+	   ],
+	   "sequence" : "KEVQFTAGQKQDIDVTTLCSTEQENINGLGASSEISMSGNFYLNQAQNALRDAYDNDTVYAFKVQFPSGKGFKFLAEVRQHTWSSGTNGVVAATFSLRLKGKPVSYVVPLAFVKN"
+	}
+
+Each document is an object with at least two attributes: the query id ('id')
+and a list of computations ('computations'). Each computation is an object with
+two attributes: 1) The tool information ('tool') containing the tool name,
+version and mentionable parameters and 2) a list of results ('results').  The
+results list itself contains an object for every distinct result. The structure
+of the result objects is defined in the corresponding modules.  It is desired
+to use the same structure for the same types of results, e.g. all homology
+search results have the same structure.
+
+In short::
+
+  {
+    "id": "the query id",
+    "computations: [
+      {
+        "tool": {
+          "name": "the tool name", 
+          "version": "the tool version", 
+          "parameterX": "parameter value"},
+        "results": [
+          {
+            "value1": "specified by module", 
+            "valueN": "specified by module"
+          }
+        ]
+      }
+    ]