plugin tutorial, some reordering of folders etc... new pull request (#8)

* rename SDK category to development

* remove aiPhilos

* rename file

* add general plugin tutorial

* add terminology and pit scheme_types in their own file

* formatting

* remove internal schemetypes

* changes how links are empedded, some typos etc

* changes to structure of terms, some editorial changes

* lots of typos, editorial stuff, some more examples

* added notes

* fix errors

sdks/php.md → dev/php.md

@@ -1,4 +1,4 @@
-# aiPhilos PHP-SDK
+# PHP-SDK
 
 [![Build Status](https://travis-ci.org/aiphilos/api-sdk-php.svg?branch=master)](https://travis-ci.org/aiphilos/api-sdk-php) [![Latest Stable Version](https://poser.pugx.org/aiphilos/api-sdk-php/v/stable)](https://packagist.org/packages/aiphilos/api-sdk-php) [![Total Downloads](https://poser.pugx.org/aiphilos/api-sdk-php/downloads)](https://packagist.org/packages/aiphilos/api-sdk-php) [![Latest Unstable Version](https://poser.pugx.org/aiphilos/api-sdk-php/v/unstable)](https://packagist.org/packages/aiphilos/api-sdk-php) [![License](https://poser.pugx.org/aiphilos/api-sdk-php/license)](https://packagist.org/packages/aiphilos/api-sdk-php)
 

dev/plugin_dev.rst

@@ -0,0 +1,171 @@
+==================
+Plugin Development
+==================
+
+It's easy to develop a working plugin for aiPhilos and it requires only three steps to actually get started.
+
+This guide assumes that you have at least created an aiPhilos account and that you have created an user so you can test your plugin against our API.
+If you are unsure how to do this, have a look at :ref:`third_party_integrations`.
+
+Apart from that your plugin needs to do the following things:
+
+Create a database and sync items
+================================
+
+ You can create a database by synching your items via a **POST-Request** against our batch-endpoint
+
+ the url for the batch-endpoint is: 
+
+ .. literalinclude:: ../shared/endpoints/POST_batch.txt
+
+
+ Because for the time being, aiPhilos is only available in german, you will need to **replace {langauge} with 'de-de' (without the quotes) and {db} with the database name of your choice**.
+
+ Database names do not need to be unique across users.
+
+ Send the items that should be synchronize in json-format like this:
+
+ .. code-block:: javascript
+
+    { items : 
+        [
+            {
+                "_id": "0",
+                "_action": "POST",
+                "additional_property1" : "additional_information",
+                "additional_property2" : "additional_information"
+            },
+            {
+                "_id": "1",
+                "_action": "POST",
+                "additional_property1" : "additional_information",
+                "additional_property2" : "additional_information"
+            }
+        ]
+    }
+
+ 
+ 
+ **Two important points:**
+
+ .. note :: *The properties '_id' and '_action' are mandatory. the _id property for every item needs to be unique and _action needs to be set to POST so the item gets indexed by aiPhilos**
+
+ .. note :: **Please be aware that the batch-endpoint has a limit of 1000 items per request. Please make sure to send the items that should be indexed in chunks of no more than 1000.**
+
+ The full documentation for the batch endpoint is available at:
+
+ .. include:: ../shared/docLinks/batchEndpointLink.txt
+
+Set an appropriate scheme
+=========================
+
+ Setting a scheme means telling aiPhilos how the data contained in the sent items is structured. To be precise: What fields it should analyze and what kind of data they hold.
+
+ Have a look at the following example:
+
+ .. code-block:: javascript
+
+    { items : 
+        [
+            {
+                "_id": "0",
+                "_action": "POST",
+                "custom_prop": 4.3                
+            },
+            {
+                "_id": "1",
+                "_action": "POST",
+                "custom_prop": 50
+            }
+        ]
+    }
+
+ Here *custom_prop* could mean several things. It could be a price, a rating or even a measurement.
+
+ By setting a scheme you can make sure that your data is interpreted as expected. Depending on the search query this could mean that that prices or ratings are used to order items appropriately, that manufacturers are recognized as such and that gtins or that the frequency of an item being ordered is being taken into account when searching with aiPhilos
+
+ To set a scheme you will need to send a **POST-Request** against our scheme-endpoint.
+
+ The url of the endpoint is: 
+
+ .. literalinclude:: ../shared/endpoints/PUT_scheme.txt
+
+
+ as before, **replace {language} with 'de-de'(without the quotes) and {db} with the name of the database that you created earlier**.
+
+ Again, the payload needs to be sent in json format, similar to this example:
+
+ .. code-block:: javascript
+
+    {
+        "custom_prop1": "general.auto",
+        "custom_prop2": "product.price",
+        "custom_prop3": "product.rating"
+    }
+
+
+ the following scheme-types are available:
+
+ .. literalinclude:: ../shared/scheme_types.txt
+
+
+ For more information about schemes have a look at :ref:`terminology_scheme`.
+
+ The full documentation for the scheme endpoint is available at:
+
+ .. include:: ../shared/docLinks/schemeEndpointLink.txt
+
+
+Search
+======
+
+ You can now use one of our search endpoints to get search your search results
+
+ The url for both endpoints is: 
+
+ .. literalinclude:: ../shared/endpoints/POST_GET_search.txt
+
+ As before, **replace {language} with 'de-de' (without quotes) and {db} with the name of you database**.
+
+ The search can be initiated either by **POST- or by GET-Request**
+
+ the following parameters can be submitted:
+
+ - **query** : the actual query string
+ - **from** : the number of found items that should be omitted when returning the result
+ - **size** : Max number of returned items
+ - **size** : the field by which to sort the results
+ - **order** : Sort direction
+ - **unsorted** : switch sorting on or off. false by default
+ - **nlp_mode** : Natural-Language-Processing (NLP) Mode
+
+ .. note :: **Only the query parameter is required. All others are optional**
+
+ depending on how you send the request, these parameters need to be sent **either as query-paramerts (GET-Request) or as part of a json payload (POST-Request)**.
+
+ example GET-Request: 
+
+ .. literalinclude:: ../shared/requests/GET_search.txt
+
+ example POST-Request:
+
+ .. literalinclude:: ../shared/requests/POST_search.json
+    :language: json
+
+Important Information
+=====================
+
+ After synchronizing items with aiPhilos and after setting a scheme, aiPhilos needs to analyze and interpret the data contained in the sent items. Depending on the complexity of the data and the amount of the items this may **take between three days and a week**. During this time search results are **not reflective of the final result**. It is advisable that you include some kind of learning mode into your plugin, which, as long as activated, does not replace the original search and to inform the user that enabling this mode is recommended as long as the synchronized data is not yet fully analyzed.
+ **Disabling this mode, after the analysis and interpretation of the synchronized items is complete, should then switch to the actual aiPhilos search via the search-endpoint.**
+
+ The full documentation for both endpoints can be looked up here:
+
+ .. include:: ../shared/docLinks/searchEndpointLinks.txt
+
+
+Further documentation
+=====================
+
+ For more detailed information regarding the API have a look at our API-Documentation:
+
+ .. include:: ../shared/docLinks/swaggerLink.txt

dev/terminology.rst

@@ -0,0 +1,10 @@
+Terminology
+===========
+
+Here you will find an overview of terms commonly associated with aiPhilos.
+
+.. toctree::
+   :maxdepth: 1
+   :name: toc-schemes
+
+   terms/schemes

dev/terms/schemes.rst

@@ -0,0 +1,38 @@
+.. _terminology_scheme:
+
+scheme/scheme-type
+==================
+
+ There are several scheme-types available. These can be set via the scheme-endpoint.
+
+ .. include:: ../../shared/docLinks/schemeEndpointLink.txt
+
+ These types help aiPhilos interpret and classify you data, so that searches can be more accurate. 
+
+ The following scheme-types can be set:
+
+ .. literalinclude:: ../../shared/scheme_types.txt
+
+ - **general.auto** aiPhilos standard mode of interpretation
+ - **general.off** tells aiPhilos not to interpret this field
+ - **product.number** a number representing the item
+ - **product.name** the name of the item
+ - **product.category** which category the item belongs to
+ - **product.description**  a description of the item
+ - **product.price** the price of the item
+ - **product.gtin** the global trade item number
+ - **product.manufacturer** who manufactures the item
+ - **product.manufacturer_number** a number representing the manufacturer
+ - **product.stock** the number of items in stock
+ - **product.supplier** who supplies the item
+ - **product.supplier_number** a number representing the supplier
+ - **product.rating** a rating for the item
+ - **product.state** information containing the state of the item
+ - **order.frequency** information on how often the item is ordered
+
+ Setting a scheme allows aiPhilos to be more specific and accurate when interpreting the items of your shop and therefore allowing for better search result.
+ Item-fields for which no scheme is set are interpreted as type *general.auto*, meaning that aiPhilos will analyze their contents and use this additional information when classifying an item.
+ If you want to explicitly exclude some fields you need to set their scheme-type to *general.off*.
+
+ **The general rule of thumb is, that the more accurate you set the scheme-types of your data (e. g. setting the manufacturers, the ratings, prices etc) the better aiPihlos will be able to interpret the items in your shop and the better the results will be eventually.**
+

getting_started/integration.rst

@@ -0,0 +1,12 @@
+Integration
+===========
+
+The semantic search of aiPhilos is utilized via the use of applications, usually called plugins or addons.
+These applications are then integrated into third party solutions (e. g. shop systems like Shopware) and enable them to leverage the capabilities of aiPhilos.
+
+.. toctree::
+   :maxdepth: 1
+   :name: toc-getting_started
+
+   third_party_how_to
+   shopware

getting_started/shopware.md

@@ -1,4 +1,4 @@
-# aiPhilos Shopware
+# Shopware
 
 To get started with our shopware plugin you will need to:
 

getting_started/third_party_how_to.rst

@@ -0,0 +1,35 @@
+.. _third_party_integrations:
+
+
+Third-Party Integrations
+========================
+
+It is very easy to integrate aiPhilos into a third-party system. To begin, you only have to:
+
+create an aiPhilos account
+--------------------------
+
+To be able to develop and test your plugin you will need to create an account at our webseite http://aiphilos.com.
+
+
+A freemium account should be sufficient to develop and test a working integration.
+
+get in touch about becoming a affiliate developer
+-------------------------------------------------
+
+Have a look at our affiliate program at https://www.aiphilos.com/partnerprogramm/entwicklungspartner and get in touch with us via one of the described methods. You will receive the neccessary information to start developing your third-party integration as an affiliate developer.
+
+
+download the neccessary SDK
+---------------------------
+
+we provide SDKs to make aiPhilos integration easier. Just Download the one you need and check out its documentation.
+
+have a look a our API documentation
+-----------------------------------
+
+https://docs.aiphilos.com/api/
+
+start developing!
+-----------------
+

index.rst

@@ -5,7 +5,11 @@ aiPhilos Documentation
 
 Welcome to the official aiPhilos documentation.
 
-If you are interested in our API-Documentation, have a look here: https://docs.aiphilos.com/api/
+.. _a link: https://domain.invalid/
+
+If you are interested in our full API-Documentation, follow this link:
+
+.. include:: shared/docLinks/swaggerLink.txt
 
 .. toctree::
    :maxdepth: 2
@@ -19,18 +23,21 @@ If you are interested in our API-Documentation, have a look here: https://docs.a
    :caption: Getting Started
    :name: sec-getting_started
 
-   getting_started/index
+   getting_started/integration  
 
 .. toctree::
    :maxdepth: 2
-   :caption: SDKs
-   :name: sec-sdks
+   :caption: Development
+   :name: sec-dev
 
-   sdks/index
+   dev/sdks
+   dev/plugin_dev
+   dev/terminology
 
 Index And Directories
 =======================
 
 * :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`
+

shared/docLinks/batchEndpointLink.txt

@@ -0,0 +1 @@
+https://docs.aiphilos.com/api/#/items/post__language__items__db__batch

shared/docLinks/schemeEndpointLink.txt

@@ -0,0 +1 @@
+https://docs.aiphilos.com/api/#/items/put__language__items__db__scheme

shared/docLinks/searchEndpointLinks.txt

@@ -0,0 +1,2 @@
+https://docs.aiphilos.com/api/#/items/get__language__items__db__search
+https://docs.aiphilos.com/api/#/items/post__language__items__db__search

shared/docLinks/swaggerLink.txt

@@ -0,0 +1 @@
+https://docs.aiphilos.com/api/

shared/endpoints/POST_GET_search.txt

@@ -0,0 +1 @@
+https://api.aiphilos.com/v1/{language}/items/{db}/search

shared/endpoints/POST_batch.txt

@@ -0,0 +1 @@
+https://api.aiphilos.com/v1/{language}/items/{db}/batch

shared/endpoints/PUT_scheme.txt

@@ -0,0 +1 @@
+https://api.aiphilos.com/v1/{language}/items/{db}/scheme

shared/requests/GET_search.txt

@@ -0,0 +1 @@
+https://api.aiphilos.com/v1/{language}/items/{db}/search?query=exampleQuery&from=0&size=0&sort=fieldToOrderBy&order=asc&unsorted=false&nlp_mode=auto

shared/requests/POST_search.json

@@ -0,0 +1,9 @@
+{
+    "query": "exampleQuery",
+    "from": 0,
+    "size": 0,
+    "sort": "fieldToOrderBy",
+    "order": "asc",
+    "unsorted": false,
+    "nlp_mode": "auto"
+  }