Add docs for API installation and usage

docs/source/t-res-api/index.rst

@@ -2,14 +2,15 @@
 Deploying the T-Res API
 ====================
 
-T-Res can also be deployed as a `FastAPI <https://fastapi.tiangolo.com/>` via `Docker <https://www.docker.com/>`, 
+T-Res can also be deployed as a `FastAPI <https://fastapi.tiangolo.com>`_ via `Docker <https://www.docker.com>`_, 
 allowing remote users to access your T-Res pipeline instead of their own local installation.
 
 The API consists of the following files:
-* `app/app_template.py`
-* `app/configs/<CONFIG_NAME>.py`
-* `app/template.Dockerfile`
-* `docker-compose.yml`
+
+* ``app/app_template.py``
+* ``app/configs/<CONFIG_NAME>.py``
+* ``app/template.Dockerfile``
+* ``docker-compose.yml``
 
 Example configuration files are provided in this repository, which can be adapted to fit your needs.
 

docs/source/t-res-api/installation.rst

@@ -3,71 +3,83 @@ Deploying the T-Res API
 =======================
 
 The T-Res API can be deployed either as a standalone docker container, 
-or via docker compose to deploy multiple configurations of the pipeline simultaneously behind a reverse-proxy (`traefik <https://traefik.io/traefik/>`).
+or via docker compose to deploy multiple configurations of the pipeline simultaneously behind 
+a reverse-proxy (`traefik <https://traefik.io/traefik/>`_).
 
-Docker and Docker Compose should be installed on your server according to the `official installation guide <https://docs.docker.com/engine/install/ubuntu/>` 
+Docker and Docker Compose should be installed on your server according to 
+the `official installation guide <https://docs.docker.com/engine/install/ubuntu/>`_ 
 before proceeding with the following steps to build and deploy the containers.
 
-A bash script `builder.sh` has been included in the repository to conveniently (re-)deploy the example API:
-.. code-block:: bash
-    ./builder.sh 
+..
+    A bash script `builder.sh` has been included in the repository to conveniently (re-)deploy the example API:
+    .. code-block:: bash
+        ./builder.sh 
 
 
 1. Building the container
 --------------
 
+To build a docker image for the app using the default configuration provided (``t-res_deezy_reldisamb-wpubl-wmtops.py``), 
+run the following bash commands from the root of the repository:  
+
 .. code-block:: bash
+
     export CONTAINER_NAME=t-res_deezy_reldisamb-wpubl-wmtops
     sudo -E docker build -f app/template.Dockerfile --no-cache --build-arg APP_NAME=${CONTAINER_NAME} -t ${CONTAINER_NAME}_image .
 
-
 2. Deploying the container
 --------------
 
+The docker image built in step 1 can then be deployed by running the following command, providing the required 
+resources are available according to the :ref: `Resources and directory structure <../getting-started/resources.html>`_ section.
+
 .. code-block:: bash
+
     sudo docker run -p 80:80 -it \
-     -v ${HOME}/toponym-resolution/resources/:/app/resources/ \
-     -v ${HOME}/toponym-resolution/geoparser/:/app/geoparser/ \
-     -v ${HOME}/toponym-resolution/utils/:/app/utils/ \
-     -v ${HOME}/toponym-resolution/preprocessing/:/app/preprocessing/ \
-     -v ${HOME}/toponym-resolution/experiments/:/app/experiments/ \
-     -v ${HOME}/nltk_data:/root/nltk_data/ \
-     -v ${HOME}/toponym-resolution/app/configs/:/app/configs/ \
+     -v ${HOME}/T-Res/resources/:/app/resources/ \
+     -v ${HOME}/T-Res/geoparser/:/app/geoparser/ \
+     -v ${HOME}/T-Res/utils/:/app/utils/ \
+     -v ${HOME}/T-Res/preprocessing/:/app/preprocessing/ \
+     -v ${HOME}/T-Res/experiments/:/app/experiments/ \
+     -v ${HOME}/T-Res/app/configs/:/app/configs/ \
      ${CONTAINER_NAME}_image:latest
 
 
 3. Deploying multiple containers via Docker Compose
 --------------
 To deploy the example configuration behind a traefik load-balancing server:
+
 .. code-block:: bash
-    HOST_URL=20.0.184.45 sudo -E docker-compose up -d
+
+    HOST_URL=<YOUR_HOST_URL> sudo -E docker-compose up -d
 
 4. Configuring your deployment
 --------------
 
-1. Add your T-Res pipeline configuration to the `app/config` directory (see `Adding a new pipeline configuration`)
-2. Optionally, you can add or edit endpoints or app behaviour in the `app/app_template.py` file
-3. Build your docker container as in step 1, setting the CONTAINER_NAME environment variable to your new configuration's name
+1. Add your T-Res pipeline configuration file to the ``app/config`` directory. This file should instantiate the ``Recogniser``, ``Linker``, and ``Ranker`` to be used in your pipeline and store them in a dictionary called ``CONFIG``, which is then imported and used by the app.
+2. Optionally, you can add or edit endpoints or app behaviour in the ``app/app_template.py`` file
+3. Build your docker container as in step 1, setting the ``CONTAINER_NAME`` environment variable to your new configuration's name
 4. Add a section to the docker-compose.yml, updating the service name, image and labels as follows:
+
     .. code-block:: yaml
+    
         <YOUR_CONFIG_NAME>:
             image: <YOUR_CONFIG_NAME>_image:latest
             restart: always
             expose:
             - 80
             volumes:
-            - ${HOME}/toponym-resolution/resources/:/app/resources/
-            - ${HOME}/toponym-resolution/geoparser/:/app/geoparser/
-            - ${HOME}/toponym-resolution/utils/:/app/utils/
-            - /${HOME}/toponym-resolution/preprocessing/:/app/preprocessing/
-            - ${HOME}/toponym-resolution/experiments/:/app/experiments/
-            - ${HOME}/nltk_data:/root/nltk_data/
+            - ${HOME}/T-Res/resources/:/app/resources/
+            - ${HOME}/T-Res/geoparser/:/app/geoparser/
+            - ${HOME}/T-Res/utils/:/app/utils/
+            - ${HOME}/T-Res/preprocessing/:/app/preprocessing/
+            - ${HOME}/T-Res/experiments/:/app/experiments/
             labels:
             - traefik.enable=true
             - traefik.http.services.<YOUR_CONFIG_NAME>.loadbalancer.server.port=80
             - traefik.http.routers.<YOUR_CONFIG_NAME>_router.service=<YOUR_CONFIG_NAME>
             - traefik.http.routers.<YOUR_CONFIG_NAME>_router.rule=Host(`<YOUR_HOST_URL>`, `0.0.0.0`) && PathPrefix(`/v2/t-res_<YOUR_CONFIG_NAME>`)
-            - "traefik.http.middlewares.test-stripprefix-rwop.stripprefix.prefixes=/v2/t-res_<YOUR_CONFIG_NAME>"
+            - traefik.http.middlewares.test-stripprefix-rwop.stripprefix.prefixes=/v2/t-res_<YOUR_CONFIG_NAME>
             - traefik.http.routers.<YOUR_CONFIG_NAME>_router.middlewares=test-stripprefix-rwop
-            command: ["poetry", "run", "uvicorn", "app:app", "--proxy-headers", "--host", "0.0.0.0", "--port", "80"]
+            command: ["poetry", "run", "uvicorn", "app:app", "--proxy-headers", "--host", "0.0.0.0", "--port", "80", "--root-path", "/v2/t-res_deezy_reldisamb-wpubl-wmtops"]
 

docs/source/t-res-api/usage.rst

@@ -2,11 +2,17 @@
 Using the T-Res API
 =======================
 
-If you deploy the T-Res API according to the steps in the previous section, it should now be available on your server as a HTTP API (be sure to expose the correct ports).
-Swagger documentation will automatically be deployed to port XXXX.
+If you deploy the T-Res API according to the steps in the previous section, 
+it should now be available on your server as a HTTP API 
+(be sure to expose the correct ports - by default, the app is deployed to port 8000). 
+Automatically generated, interactive documentation (created by `Swagger`) is available at the ``/docs`` endpoint.
 
 The following example shows how to query the API via curl to resolve the toponyms in a single sentence:
+
 .. code-block:: bash
-    curl ...
+    
+    curl -X GET http://20.0.184.45:8000/v2/t-res_deezy_reldisamb-wpubl-wmtops/toponym_resolution \
+    -H "Content-Type: application/json" \
+    -d '{"text": "Harvey, from London;Thomas and Elizabeth, Barnett.", "place": "Manchester", "place_wqid": "Q18125"}'
 
-See the `app/api_usage.ipynb` notebook for more examples of how to use the API's various endpoints via Python.
+See the ``app/api_usage.ipynb`` notebook for more examples of how to use the API's various endpoints via Python.