updates to README and indexes

caimira/docs/mkdocs/docs/code_documentation/index.md

@@ -1,4 +1,4 @@
 # Code-related Documentation
 
 * [CAiMIRA REST API](rest_api.md)
-* [CAiMIRA models](models.md)
+* [CAiMIRA Models](models.md)

caimira/docs/mkdocs/docs/full_diameter_dependence.md

@@ -1,4 +1,4 @@
-# Diameter-dependent model
+# Diameter-dependent Model
 
 This section describes the CAiMIRA model and its dependence on the Particles diameter. A Unified Modeling Language (UML) diagram describing all the data classes and their relations can be found [here](#caimira-uml-diagram), at the bottom of the document.
 

caimira/docs/mkdocs/docs/index.md

@@ -1,20 +1,18 @@
 # Welcome to CAiMIRA’s documentation!
 
+This documentation provides comprehensive guidance on the CERN Airborne Model for Risk Assessment (CAiMIRA) tool. 
+
+It includes details on the diameter-dependent mathematical model and the code developed based on the underlying published research. It also covers documentation on the code itself, including explanations of the main module (`models.py`), and the recently added REST API feature, providing a through understanding of the CAiMIRA's functionality.
+
 # Contents:
 
-* [Project README](project_README.md)
+* [Project Overview](project_overview.md)
 
 * [Diameter-dependent Model](full_diameter_dependence.md)
-    * [Context](full_diameter_dependence.md#context)
-    * [Expiration](full_diameter_dependence.md#expiration)
-    * [Emission Rate - vR(D)](full_diameter_dependence.md#emission-rate-vrd)
-    * [Virus Concentration - C(t, D)](full_diameter_dependence.md#virus-concentration-ct-d)
-    * [Dose - vD](full_diameter_dependence.md#dose-vd)
-    * [CO<sub>2</sub> Concentration](full_diameter_dependence.md#co2-concentration)
-    * [CAiMIRA UML Diagram](full_diameter_dependence.md#caimira-uml-diagram)
-    * [REFERENCES](full_diameter_dependence.md#references)
 
 * [Code-related Documentation](code_documentation/index.md)
 
     * [CAiMIRA REST API](code_documentation/rest_api.md)
-    * [CAiMIRA models](code_documentation/models.md)
+    * [CAiMIRA Models](code_documentation/models.md)
+
+* [Open Source Acknowledgments](open_source_acknowledgments.md)

caimira/docs/mkdocs/docs/project_README.md → caimira/docs/mkdocs/docs/project_overview.md

@@ -24,7 +24,7 @@ While the SARS-CoV-2 virus is in circulation among the population, the notion of
 Each event modelled is unique, and the results generated therein are only as accurate as the inputs and assumptions.
 
 ## Authors
-CAiMIRA was developed by following members of CERN - European Council for Nuclear Research (visit https://home.cern/):
+CAiMIRA was developed by following members of CERN - European Council for Nuclear Research (visit [https://home.cern/](https://home.cern/)):
 
 Andre Henriques<sup>1</sup>, Luis Aleixo<sup>1</sup>, Marco Andreini<sup>1</sup>, Gabriella Azzopardi<sup>2</sup>, James Devine<sup>3</sup>, Philip Elson<sup>4</sup>, Nicolas Mounet<sup>2</sup>, Markus Kongstein Rognlien<sup>2,6</sup>, Nicola Tarocco<sup>5</sup>
 
@@ -47,15 +47,15 @@ CAiMIRA – CERN Airborne Model for Indoor Risk Assessment tool
 
 **For use of the CAiMIRA model**
 
-Henriques A, Mounet N, Aleixo L, Elson P, Devine J, Azzopardi G, Andreini M, Rognlien M, Tarocco N, Tang J. (2022). Modelling airborne transmission of SARS-CoV-2 using CARA: risk assessment for enclosed spaces. _Interface Focus 20210076_. https://doi.org/10.1098/rsfs.2021.0076
+Henriques A, Mounet N, Aleixo L, Elson P, Devine J, Azzopardi G, Andreini M, Rognlien M, Tarocco N, Tang J. (2022). Modelling airborne transmission of SARS-CoV-2 using CARA: risk assessment for enclosed spaces. _Interface Focus 20210076_. [https://doi.org/10.1098/rsfs](https://doi.org/10.1098/rsfs).2021.0076
 
 Reference on the Short-range expiratory jet model from:
 Jia W, Wei J, Cheng P, Wang Q, Li Y. (2022). Exposure and respiratory infection risk via the short-range airborne route. _Building and Environment_ *219*: 109166.
-https://doi.org/10.1016/j.buildenv.2022.109166
+[https://doi.org/10.1016/j.buildenv.2022.109166](https://doi.org/10.1016/j.buildenv.2022.109166)
 
 ***Open Source Acknowledgments***
 
-For a detailed list of the open-source dependencies used in this project along with their respective licenses, please refer to [License Information](open-source-licences/README.md). This includes both the core dependencies specified in the project's requirements and their transitive dependencies.
+For a detailed list of the open-source dependencies used in this project along with their respective licenses, please refer to [Open Source Acknowledgments](open_source_acknowledgments.md). This includes both the core dependencies specified in the project's requirements and their transitive dependencies.
 
 The information also features a distribution diagram of licenses and a brief description of each of them.
 
@@ -82,12 +82,12 @@ In no event shall the authors or copyright holders be liable for any claim, dama
 ## Running CAiMIRA locally
 
 The easiest way to run a version of CAiMIRA Calculator is to use docker. A pre-built
-image of CAiMIRA is made available at https://gitlab.cern.ch/caimira/caimira/container_registry.
+image of CAiMIRA is made available at [https://gitlab.cern.ch/caimira/caimira/container_registry](https://gitlab.cern.ch/caimira/caimira/container_registry).
 In order to run CAiMIRA locally with docker, run the following:
 
     $ docker run -it -p 8080:8080 gitlab-registry.cern.ch/caimira/caimira/calculator
 
-This will start a local version of CAiMIRA, which can be visited at http://localhost:8080/.
+This will start a local version of CAiMIRA, which can be visited at [http://localhost:8080/](http://localhost:8080/).
 
 
 ## Folder structure
@@ -102,7 +102,7 @@ The folder layout follows best practices as described [here](https://ianhopkinso
 
 ## Development guide
 
-CAiMIRA is also mirrored to Github if you wish to collaborate on development and can be found at: https://github.com/CERN/caimira
+CAiMIRA is also mirrored to Github if you wish to collaborate on development and can be found at: [https://github.com/CERN/caimira](https://github.com/CERN/caimira)
 
 ### Installing CAiMIRA in editable mode
 
@@ -146,7 +146,7 @@ To run the calculator on a different URL path:
 python -m cern_caimira.apps.calculator --prefix=/mycalc
 ```
 
-Each of these commands will start a local version of CAiMIRA, which can be visited at http://localhost:8080/.
+Each of these commands will start a local version of CAiMIRA, which can be visited at [http://localhost:8080/](http://localhost:8080/).
 
 ### Documentation
 
@@ -242,7 +242,7 @@ python -m pytest
 
 CAiMIRA includes a profiler designed to identify performance bottlenecks. The profiler is enabled when the environment variable `CAIMIRA_PROFILER_ENABLED` is set to 1.
 
-When visiting http://localhost:8080/profiler, you can start a new session and choose between [PyInstrument](https://github.com/joerick/pyinstrument) or [cProfile](https://docs.python.org/3/library/profile.html#module-cProfile). The app includes two different profilers, mainly because they can give different information.
+When visiting [http://localhost:8080/profiler](http://localhost:8080/profiler), you can start a new session and choose between [PyInstrument](https://github.com/joerick/pyinstrument) or [cProfile](https://docs.python.org/3/library/profile.html#module-cProfile). The app includes two different profilers, mainly because they can give different information.
 
 Keep the profiler page open. Then, in another window, navigate to any page in CAiMIRA, for example generate a new report. Refresh the profiler page, and click on the `Report` link to see the profiler output.
 
@@ -275,6 +275,8 @@ The response format will be:
 }
 ```
 
+For further details please refer to the [REST API official documentation](../code_documentation/rest_api/).
+
 ### Building the whole environment for local development
 
 ```
@@ -307,19 +309,19 @@ cd app-config
 CURRENT_UID=$(id -u):$(id -g) docker compose up
 ```
 
-Then visit http://localhost:8080/.
+Then visit [http://localhost:8080/](http://localhost:8080/).
 
 ### Setting up the application on OpenShift
 
-The https://cern.ch/caimira application is running on CERN's OpenShift platform. In order to set it up for the first time, we followed the documentation at https://paas.docs.cern.ch/. In particular we:
+The [https://cern.ch/caimira](https://cern.ch/caimira) application is running on CERN's OpenShift platform. In order to set it up for the first time, we followed the documentation at [https://paas.docs.cern.ch/](https://paas.docs.cern.ch/). In particular we:
 
  * Added the OpenShift application deploy key to the GitLab repository
  * Created a Python 3.12 (the highest possible at the time of writing) application in OpenShift
  * Configured a generic webhook on OpenShift, and call that from the CI of the GitLab repository
 
 ### Updating the caimira-test.web.cern.ch instance
 
-We have a replica of https://caimira.web.cern.ch running on http://caimira-test.web.cern.ch. Its purpose is to simulate what will happen when
+We have a replica of [https://caimira.web.cern.ch](https://caimira.web.cern.ch) running on [http://caimira-test.web.cern.ch](http://caimira-test.web.cern.ch). Its purpose is to simulate what will happen when
 a feature is merged. To push your changes to caimira-test, simply push your branch to `live/caimira-test` and the CI pipeline will trigger the
 deployment. To push to this branch, there is a good chance that you will need to force push - you should always force push with care and
 understanding why you are doing it. Syntactically, it will look something like (assuming that you have "upstream" as your remote name,
@@ -440,35 +442,33 @@ $ oc create secret generic \
 ### External APIs
 
 - **Geographical location:**
-There is one external API call to fetch required information related to the geographical location inserted by a user.
-The documentation for this geocoding service is available at https://developers.arcgis.com/rest/geocode/api-reference/geocoding-suggest.htm .
-Please note that there is no need for keys on this API call. It is **free-of-charge**.
+    There is one external API call to fetch required information related to the geographical location inserted by a user.
+    The documentation for this geocoding service is available at [https://developers.arcgis.com/rest/geocode/api-reference/geocoding-suggest.htm](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-suggest.htm) .
+    Please note that there is no need for keys on this API call. It is **free-of-charge**.
 
 - **Humidity and Inside Temperature:**
-There is the possibility of using one external API call to fetch information related to a location specified in the UI. The data is related to the inside temperature and humidity taken from an indoor measurement device. Note that the API currently used from ARVE is only available for the `CERN theme` as the authorised sensors are installed at CERN."
+     for the `CERN theme` as the authorised sensors are installed at CERN."
 
 - **ARVE:**
-
-The ARVE Swiss Air Quality System provides trusted air data for commercial buildings in real-time and analyzes it with the help of AI and machine learning algorithms to create actionable insights.
-
-Create secret:
-
-```console
-$ read ARVE_CLIENT_ID
-$ read ARVE_CLIENT_SECRET
-$ read ARVE_API_KEY
-$ oc create secret generic \
-  --from-literal="ARVE_CLIENT_ID=$ARVE_CLIENT_ID" \
-  --from-literal="ARVE_CLIENT_SECRET=$ARVE_CLIENT_SECRET" \
-  --from-literal="ARVE_API_KEY=$ARVE_API_KEY" \
-  arve-api
-```
+    The ARVE Swiss Air Quality System provides trusted air data for commercial buildings in real-time and analyzes it with the help of AI and machine learning algorithms to create actionable insights.
+
+    Create secret:
+
+    ```console
+    $ read ARVE_CLIENT_ID
+    $ read ARVE_CLIENT_SECRET
+    $ read ARVE_API_KEY
+    $ oc create secret generic \
+    --from-literal="ARVE_CLIENT_ID=$ARVE_CLIENT_ID" \
+    --from-literal="ARVE_CLIENT_SECRET=$ARVE_CLIENT_SECRET" \
+    --from-literal="ARVE_API_KEY=$ARVE_API_KEY" \
+    arve-api
+    ```
 
 - **CERN Data Service:**
+    The CERN data service collects data from various sources and expose them via a REST API endpoint.
 
-The CERN data service collects data from various sources and expose them via a REST API endpoint.
-
-The service is enabled when the environment variable `DATA_SERVICE_ENABLED` is set to 1.
+    The service is enabled when the environment variable `DATA_SERVICE_ENABLED` is set to 1.
 
 ## Update configuration
 

caimira/docs/mkdocs/mkdocs.yml

@@ -4,11 +4,12 @@ theme:
 
 nav:
   - Home: index.md
-  - Project README: project_README.md
-  - Diameter-dependent model: full_diameter_dependence.md
-  - Code-related documentation:
+  - Project Overview: project_overview.md
+  - Diameter-dependent Model: full_diameter_dependence.md
+  - Code-related Documentation:
       - CAiMIRA REST API: code_documentation/rest_api.md
       - CAiMIRA models: code_documentation/models.md
+  - Open Source Acknowledgments: open_source_acknowledgments.md
 
 markdown_extensions:
   - pymdownx.arithmatex: