reldbs: better documentation

00.DOCUMENTATION/A-Introduction/README.md

@@ -27,55 +27,73 @@ For the rest of the exemples we assume you cloned the code in a directory called
 
 So the procedure to integrate is basically just to extract the tinawebJS distribution in your `static` directory.
 
-There are two exceptions are:
-  - the html starting point itself:  
-    - to use it as is:
+There are two exceptions are the html page and the companion backends:
+  - you can adapt paths for the html starting point itself to any url prefix:  
+    1) go into the root directory of projectExplorer in your static dir
+    ```
+    # with our exemple
+    cd path/to/yourapp/static/ProjectExplorer
+    ```
+
+    2) apply the changing paths tool `adapt_html_paths.sh` like this:
+    ```
+    bash twtools/adapt_html_paths.sh 'static/projectExplorer/'
+    #                                ------------------------
+    #                      the relative url prefix in your deployment routes
+    ```
+    this creates a new file: `explorerjs.prod.html`
+
+    3) now just link to the new file from your html dir or templates dir
+    ```
+    # cd back/to/your/app/root (or html files dir)
+    cd ../../  
+    ln -s static/ProjectExplorer/explorerjs.prod.html explorerjs.html
+
+    # now `ls -l` should show something like this:
+    # - HTML ELEMENTS OF YOUR APP
+    # - HTML ELEMENTS OF YOUR APP
+    # - explorerjs.html -> static/ProjectExplorer/explorerjs.prod.html
+    ```
+
+    4) finally update the settings property `ourlibs` (path to twlibs) with the same URL prefix
+    ```
+    nano static/ProjectExplorer/settings_explorerjs.js
+
+      ----------------- [IN NANO] --------------------
+       (...)
+       TWConf.paths = {
+         'ourlibs': 'static/ProjectExplorer/twlibs',    // <=== here
+         ...
+       }
+       (...)
+      -----------------------------------------------
+    ```
 
-      1) go into the root directory of projectExplorer in your static dir
-      ```
-      # with our exemple
-      cd path/to/yourapp/static/ProjectExplorer
-      ```
+    - to use it within a different GUI layout: take our html as an exemple and create your own html importing the same libs and exposing the same div ids.
+    - the directory `twpresets/` contains specific variants of `settings_explorerjs` for some common deployment tasks of the ISCPIF (comex, gargantext)
 
-      2) apply the changing paths tool `adapt_html_paths.sh` like this:
-      ```
-      bash twtools/adapt_html_paths.sh 'static/projectExplorer/'
-      #                                ------------------------
-      #                      the relative url prefix in your deployment routes
-      ```
-      this creates a new file: `explorerjs.prod.html`
 
-      3) now just link to the new file from your html dir or templates dir
-      ```
-      # cd back/to/your/app/root (or html files dir)
-      cd ../../  
-      ln -s static/ProjectExplorer/explorerjs.prod.html explorerjs.html
-
-      # now `ls -l` should show something like this:
-      # - HTML ELEMENTS OF YOUR APP
-      # - HTML ELEMENTS OF YOUR APP
-      # - explorerjs.html -> static/ProjectExplorer/explorerjs.prod.html
-      ```
+  - optionally, to deploy the backends under `twbackends`:
+
+      1) they are the only server-side elements of the tina distribution. While part of the distribution, they are **standalone micro-servers**.
+
+      2) they contain their own documentation as to how to run them on a webserver
+      - for the twitter backend setup, you should follow [this section of the twitterAPI readme](https://github.com/moma/ProjectExplorer/blob/master/twbackends/twitterAPI2/README.md#on-a-real-server)
+      - for the CSV/CortextDB backend, the easiest is to serve the php files as an additional location of your static server, as explained in the [this section of the PHP backend's readme](https://github.com/moma/ProjectExplorer/blob/master/twbackends/phpAPI/README.md#prerequisites)  
 
-      4) finally update the settings property `ourlibs` (path to twlibs) with the same URL prefix
+    3) once they are running, the communication between them and the main tinaweb client module happens via XHR requests: therefore they can actually reside in any convenient place for your deployment. You just need to set the http paths accordingly in the `relatedDocsAPIS` entry of ProjectExplorer's settings. For instance, with the locations suggested in the documentation above, the configuration in `settings_explorerjs.js` would be like this:
       ```
       nano static/ProjectExplorer/settings_explorerjs.js
 
         ----------------- [IN NANO] --------------------
          (...)
-         TWConf.paths = {
-           'ourlibs': 'static/ProjectExplorer/twlibs',    // <=== here
-           ...
+         TWConf.relatedDocsAPIS = {
+             "twitter": "http://127.0.0.1:5000/twitter_search",
+             "CortextDB": "twbackends/phpAPI",
+             "csv": "twbackends/phpAPI"
          }
          (...)
         -----------------------------------------------
       ```
 
-    - to use it within a different GUI layout: take our html as an exemple and create your own html importing the same libs and exposing the same div ids.
-    - the directory `twpresets/` contains specific variants of `settings_explorerjs` for some common deployment tasks of the ISCPIF (comex, gargantext)
-
-  - optionally, the backends under `twbackends`:
-    - they are the only server-side elements of the tina distribution
-    - while part of the distribution, they are **standalone micro-servers**
-    - they contain their own readme as to how to run them on a server
-    - once they are configured or run, the communication between them and the main tinaweb client module happens via XHR requests: therefore they can actually reside in any convenient place for your deployment.
+    4) finally, to use these backends as related documents search engines for a given graph, you'll need to configure your `db.json` file [as explained here](https://github.com/moma/ProjectExplorer/blob/master/00.DOCUMENTATION/A-Introduction/servermenu_config.md#more-relateddocs-settings). You can also find real-life examples in this distribution's `db.json` file.

twbackends/twitterAPI2/README.md

@@ -40,6 +40,29 @@ python3 topPapers_flask_server.py --cors
 #### On a real server
 Use nohup or gunicorn to detach the process or make it into a full-fledged server.
 
+For instance for a ProjectExplorer server you can follow these 3 steps.
+
+1. run the backend with nohup
+```
+cd ${YOUR_PROJECT_EXPLORER_DIR}/twbackends/twitterAPI2
+nohup python3 topPapers_flask_server.py &
+```
+2. add a proxy location to the nginx server's conf:
+```
+location /twitter_search {
+     proxy_pass http://0.0.0.0:5000 ;
+     proxy_redirect off ;
+}
+```
+
+3. fill the corresponding info in ProjectExplorer's settings_explorerjs.js
+```
+TWConf.relatedDocsAPIS = {
+  "twitter": "http://${YOUR_SERVER_IP}/twitter_search",
+  (...)
+}
+```
+
 
 ## More info
 

twlibs3/README.md

+### 3rd party libraries for ProjectExplorer