refactor and improve the apib docs + add details about persons search

conf/bhs_api_site

@@ -8,7 +8,7 @@ server {
 
 	location /v1/docs {
         default_type text/html;
-        alias /home/bhs/api/docs/index.html;
+        alias /home/bhs/api/docs/_build/index.html;
     }
 
     location / {

docs/README.md

@@ -0,0 +1,5 @@
+# dbs-back documentation hub
+
+## API documentation
+
+The API documentation is served at http://devapi.dbs.bh.org.il/v1/docs

docs/_build/README.md

@@ -0,0 +1,7 @@
+# documentation source files
+
+This directory contains the api documentation files built from the _sources files
+
+**Important Notice**
+
+If you just want to read the documentation, go to https://github.com/Beit-Hatfutsot/dbs-back/tree/dev/docs

docs/_sources/README.md

@@ -0,0 +1,7 @@
+# documentation source files
+
+This directory contains the source files used to build the documentation files at the parent docs directory.
+
+**Important Notice**
+
+If you just want to read the documentation, go to https://github.com/Beit-Hatfutsot/dbs-back/tree/dev/docs

docs/_sources/index.apib

@@ -0,0 +1,10 @@
+FORMAT: 1A
+
+
+# API for Beit-Hatfutsot Databases
+Welcome to the docs for the API server of the museum of the Jewish people.
+
+Read this if you think the Jewish people haven't suffered enough.
+
+<!-- include(search/search.md) -->
+<!-- include(items/items.md) -->

docs/_sources/items/item_base.json

@@ -0,0 +1,13 @@
+{
+  // every item gets a unique slug which identifies the item
+  "Slug": {
+    "En": "UNIQUE_ITEM_SLUG_IN_ENGLISH",
+    "He": "UNIQUE_ITEM_SLUG_IN_HEBREW"
+  },
+  // every item has a header title / text, the value depends on the item
+  // for example - for place, it will be the name of the place, for person - the name of the person etc..
+  "Header": {
+    "En": "ENGLISH_HEADER",
+    "He": "HEBREW_HEADER"
+  }
+}

docs/_sources/items/item_person.json

@@ -0,0 +1,15 @@
+{
+  // the BHP item id
+  "UnitId": 72312,
+  // person slugs contain the tree number, version and person id (within that tree)
+  // person slugs are the same for both english and hebrew
+  "Slug": {
+    "En": "person_1130%3B0.I3552",
+    "He": "person_1130%3B0.I3552"
+  },
+  // name of the person - same value is in both english and hebrew
+  "Header": {
+    "En": "Moshe Fakeuser",
+    "He": "Moshe Fakeuser"
+  }
+}

docs/_sources/items/item_place.json

@@ -0,0 +1,23 @@
+{
+  "PlaceTypeDesc": {
+    "En": "City",
+    "He": "\u05e2\u05d9\u05e8"
+  },
+  // plain text, long article about this place (may contain newlines)
+  "UnitText1": {
+    "En": "",
+    "He": ""
+  },
+  // the BHP item id
+  "UnitId": 72312,
+  // slug is comprised of "place_header"
+  "Slug": {
+    "En": "place_paris",
+    "He": "\u05de\u05e7\u05d5\u05dd_\u05e4\u05e8\u05d9\u05e1"
+  },
+  // name of the place
+  "Header": {
+    "En": "PARIS",
+    "He": "\u05e4\u05e8\u05d9\u05e1"
+  }
+}

docs/_sources/items/items.md

@@ -0,0 +1,45 @@
+# Group Item
+
+## Get Item/s [GET /v1/item/{slugs}]
+Get specific items according to their slugs
+
++ Parameters
+    + slugs: `place_paris,person_1130;0.I3552` (string, required)
+        Comma-separated list of slugs to fetch
+
++ Response 200 (application/json)
+
+            [
+                // list of item objects (see Item Models section for details)
+                <!-- include(item_place.json) -->,
+                <!-- include(item_person.json) -->
+            ]
+
+
+# Group Item Models
+Every item represents an item in one of our collections.
+
+Each item have some common properties and some unique properties depending on the collection.
+
+## Item
+The base item, includes attributes common to all collections.
+
++ Model (application/json)
+
+            <!-- include(item_base.json) -->
+
+
+## Place
+Extends the base item with place specific attributes
+
++ Model (application/json)
+
+            <!-- include(item_place.json) -->
+
+
+## Person
+Extends the base item with person specific attributes
+
++ Model (application/json)
+
+            <!-- include(item_person.json) -->

docs/_sources/search/persons_advanced_search_params.md

@@ -0,0 +1 @@
+{?collection,q,from_,size,first,first_t,last,last_t,pob,pob_t,pom,pom_t,pod,pod_t,yob,yob_t,yob_v,yom,yom_t,yom_v,yod,yod_t,yod_v,sex,treenum}

docs/_sources/search/persons_advanced_search_params_description.md

@@ -0,0 +1,32 @@
++ Parameters
+    + collection: `persons` (enum, required) - The advanced persons search requires collection to be persons
+        + Members
+            + persons
+    + q (string, optional) - same as in [general search](#database-search-general-search), but optional
+    + from_ (number, optional) - see [general search](#database-search-general-search)
+    + size (number, optional) - see [general search](#database-search-general-search)
+    + first (string, optional) - first name
+    + first_t: `like` (enum, optional) - first name <!-- include(text_search_type_members.md) -->
+    + last (string, optional) - last name
+    + last_t: `like` (enum, optional) - last name <!-- include(text_search_type_members.md) -->
+    + pob (string, optional) - place of birth
+    + pob_t: `like` (enum, optional) - place of birth <!-- include(text_search_type_members.md) -->
+    + pom (string, optional) - place of marriage
+    + pom_t: `like` (enum, optional) - place of marriage <!-- include(text_search_type_members.md) -->
+    + pod (string, optional) - place of death
+    + pod_t: `like` (enum, optional) - place of death <!-- include(text_search_type_members.md) -->
+    + yob (number, optional) - year of birth
+    + yob_t: `pmyears` (enum, optional) - year of birth <!-- include(year_search_type_members.md) -->
+    + yob_v: <!-- include(year_search_v_param.md) -->
+    + yom (number, optional) - year of marriage
+    + yom_t: `pmyears` (enum, optional) - year of marriage <!-- include(year_search_type_members.md) -->
+    + yom_v: <!-- include(year_search_v_param.md) -->
+    + yod (number, optional) - year of death
+    + yod_t: `pmyears` (enum, optional) - year of death <!-- include(year_search_type_members.md) -->
+    + yod_v: <!-- include(year_search_v_param.md) -->
+    + sex (enum, optional) - **F**: Female, **M**: Male, **U**: Unkonwn / Unspecified
+        + Members
+            + F
+            + M
+            + U
+    + treenum (number, optional) - Beit Hatfutsot tree number

docs/_sources/search/search.md

@@ -0,0 +1,42 @@
+# Group Database Search
+
+
+## General search [GET /v1/search{?q,collection,from_,size,first,with_persons}]
+
+This view initiates a full text search on all our collections.
+
++ Parameters
+    + q: `netta` (string)
+        The search string, using [elasticsearch query string syntax](https://www.elastic.co/guide/en/elasticsearch/reference/2.4/query-dsl-query-string-query.html#query-string-syntax)
+    + collection (string, optional)
+        A comma separated list of collections to search in.
+        + Members
+            + movies
+            + places
+            + personalities
+            + photoUnits
+            + familyNames
+            + persons
+    + from_ (number, optional)
+        Which search result to start from.
+    + size (number, optional)
+        How many results to return.
+    + with_persons (enum, optional)
+        If to include persons results when searching over multiple collections
+        + Members
+            + 1
+
++ Response 200 (application/json)
+
+            <!-- include(search_results.json) -->
+
+
+## Persons advanced search [GET /v1/search<!-- include(persons_advanced_search_params.md) -->]
+
+Advanced search on persons, must have at last one of either q param (as in general search) or the person specific search params
+
+<!-- include(persons_advanced_search_params_description.md) -->
+
++ Response 200 (application/json)
+
+            <!-- include(search_results.json) -->

docs/_sources/search/search_results.json

@@ -0,0 +1,9 @@
+{
+    "hits": {
+        "hits": [
+            // list of item objects, depending on the searched collections
+            // see Items section for details about the structure of item objects
+        ],
+        "total": 1 // total number of results
+    }
+}

docs/_sources/search/text_search_type_members.md

@@ -0,0 +1,5 @@
+search type
+        + Members
+            + exact
+            + like
+            + starts

docs/_sources/search/year_search_type_members.md

@@ -0,0 +1,4 @@
+search type
+        + Members
+            + exact
+            + pmyears

docs/_sources/search/year_search_v_param.md

@@ -0,0 +1 @@
+`2` (number, optional) - if the corresponding search type is pmyears, this is the value to add / subtract