Merge pull request #115 from iai-group/feature/109-Add-documentation-…

…on-server-and-client

Feature/109-Add-documentation-on-server-and-client

README.md

@@ -51,7 +51,7 @@ By default, the server will run locally on port 5000. In case you want to run th
 
 ## PKG Client
 
-The user interface is a React application that communicates with the server to manage the PKG. More details on how to run PKG Client can be found [here](pkg-client/README.md).
+The user interface is a React application that communicates with the server to manage the PKG. More details on how to run PKG Client can be found [here](pkg_client/README.md).
 
 :warning: Note that you need to update `PKG_API_BASE_URL` in the [configuration](pkg_client/public/config.json) in case the server is not running on the default port.
 

docs/source/pkg_client.rst

@@ -0,0 +1,30 @@
+PKG Client
+==========
+
+PKG Client is a simple and user-friendly user interface, based on React, to manage a PKG. The management is done through requests sent to the server.
+
+Run PKG Client
+--------------
+
+Node.js and npm are required to run PKG Client, more information on how to install them can be found `here <https://docs.npmjs.com/downloading-and-installing-node-js-and-npm>`.
+
+To start PKG Client, run the following commands in the directory `pkg_client`:
+
+.. code-block:: bash
+
+    npm install
+    npm start
+
+Note that `npm install` only needs to be run once, unless the dependencies change. For more information on how to run the client, refer to the `README <https://github.com/iai-group/pkg-api/blob/main/pkg_client/README.md>` in the `pkg_client` directory.
+
+In case the server is not running on the default port (i.e., 5000), `PKG_API_BASE_URL` in `pkg_client/public/config.json` must be updated accordingly.
+
+Features
+--------
+
+PKG Client has the following pages:
+
+* **Login/Registration**: To access their PKG, users must be logged in. If they do not have an account, they can register.
+* **Home**: The home page provides a text input field where users can enter their management instructions (i.e., add, remove, and retrieve statements) in natural language. After being processed by the server, the outcome of the instructions is displayed. The home page also provides a button to visualize the PKG.
+* **Populate PKG**: Users can populate their PKG by adding or removing statements via a form. This feature assumes that the user is familiar with the `PKG vocabulary <https://iai-group.github.io/pkg-vocabulary/>`.
+* **Explore PKG**: Users can visualize their PKG or a part of it as an RDF graph. The visualization is generated based on the results of a SPARQL query, hence, this feature is intended for advanced users.

docs/source/pkg_server.rst

@@ -0,0 +1,29 @@
+Server
+======
+
+The backend server is a `Flask <https://flask.palletsprojects.com/en/3.0.x/>` server. It is responsible for connecting the users and service providers to PKGs.
+
+Run server
+----------
+
+Before starting the server, make sure that the `requirements <https://github.com/iai-group/pkg-api/blob/main/requirements.txt>` are installed and that CORS is disabled in your web browser.
+
+To start the server, run the following command:
+
+.. code-block:: bash
+
+    flask --app pkg_api/server run --debug
+
+Note the `--debug` flag is optional, but it is recommended to use it during development.
+
+By default, the server will run locally on port 5000. In case you want to run the server on a different port, you can specify the port using the `--port` flag.
+
+Routes
+------
+
+The server has four main routes that relate to the :doc:`features available <pkg_client>` in the PKG Client:
+
+* `/auth`: Handles the authentication of users and service providers.
+* `/nl`: Handles natural language instructions provided by users to manage the PKG.
+* `/statements`: Manages the addition and deletion of statements via forms.
+* `/explore`: Handles SPARQL queries for the visualization of the PKG.