From 3d5ca4894fa1743ac81a4f6b269000ad2620b882 Mon Sep 17 00:00:00 2001 From: lrdossan Date: Mon, 18 Nov 2024 16:21:23 +0100 Subject: [PATCH] Re-named files and adapted scripts --- README.md | 2 +- caimira/docs/Dockerfile | 4 +-- caimira/docs/mkdocs/docs/code/architecture.md | 9 ++++++ .../{code_documentation => code}/rest_api.md | 24 ++------------- caimira/docs/mkdocs/docs/index.md | 28 ++++++++++-------- .../docs/{project_overview => root}/about.md | 23 +++++++------- .../{project_overview => root}/deployment.md | 19 ++++++++++++ .../installation.md | 4 +-- .../open_source_acknowledgments.md | 0 .../physics_model.md} | 14 ++------- .../CAiMIRA}/full_guide.md | 2 +- .../CAiMIRA}/img/window_opening.png | Bin .../CAiMIRA}/img/window_type.PNG | Bin .../CAiMIRA}/quick_guide.md | 2 +- caimira/docs/mkdocs/mkdocs.yml | 28 ++++++++++-------- caimira/docs/style_docs.py | 4 +-- 16 files changed, 83 insertions(+), 80 deletions(-) create mode 100644 caimira/docs/mkdocs/docs/code/architecture.md rename caimira/docs/mkdocs/docs/{code_documentation => code}/rest_api.md (93%) rename caimira/docs/mkdocs/docs/{project_overview => root}/about.md (85%) rename caimira/docs/mkdocs/docs/{project_overview => root}/deployment.md (84%) rename caimira/docs/mkdocs/docs/{project_overview => root}/installation.md (98%) rename caimira/docs/mkdocs/docs/{project_overview => root}/open_source_acknowledgments.md (100%) rename caimira/docs/mkdocs/docs/{code_documentation/diameter_normalization.md => root/physics_model.md} (98%) rename caimira/docs/mkdocs/docs/{project_overview/user_guide => user_interfaces/CAiMIRA}/full_guide.md (99%) rename caimira/docs/mkdocs/docs/{project_overview/user_guide => user_interfaces/CAiMIRA}/img/window_opening.png (100%) rename caimira/docs/mkdocs/docs/{project_overview/user_guide => user_interfaces/CAiMIRA}/img/window_type.PNG (100%) rename caimira/docs/mkdocs/docs/{project_overview/user_guide => user_interfaces/CAiMIRA}/quick_guide.md (98%) diff --git a/README.md b/README.md index c51a1ddd..e1de672a 100644 --- a/README.md +++ b/README.md @@ -176,7 +176,7 @@ Run the `style_docs.py` script to apply custom styles, move required files, and ``` python style_docs.py \ -&& mv sphinx/_build/markdown/index.md mkdocs/docs/code_documentation/models.md \ +&& mv sphinx/_build/markdown/index.md mkdocs/docs/code/models.md \ && pyreverse -o png -p UML-CAiMIRA --output-directory mkdocs/docs ../src/caimira/calculator/models/models.py ``` diff --git a/caimira/docs/Dockerfile b/caimira/docs/Dockerfile index 36d4302b..37784ed6 100644 --- a/caimira/docs/Dockerfile +++ b/caimira/docs/Dockerfile @@ -25,8 +25,8 @@ WORKDIR /app/docs # Run the Python script to update markdown files, move it, and generate UML diagram RUN python3 style_docs.py \ -&& mv sphinx/_build/markdown/index.md mkdocs/docs/code_documentation/models.md \ -&& pyreverse -o png -p UML-CAiMIRA --output-directory mkdocs/docs/code_documentation ../src/caimira/calculator/models/models.py +&& mv sphinx/_build/markdown/index.md mkdocs/docs/code/models.md \ +&& pyreverse -o png -p UML-CAiMIRA --output-directory mkdocs/docs/code ../src/caimira/calculator/models/models.py # Mkdocs directory WORKDIR /app/docs/mkdocs diff --git a/caimira/docs/mkdocs/docs/code/architecture.md b/caimira/docs/mkdocs/docs/code/architecture.md new file mode 100644 index 00000000..93ca6693 --- /dev/null +++ b/caimira/docs/mkdocs/docs/code/architecture.md @@ -0,0 +1,9 @@ +This page contains a Unified Modeling Language (UML) diagram describing all the data classes and their relations. + +## CAiMIRA UML Diagram + +The following diagram describes all the data classes and their relations under the `models.py` file. Click the diagram to zoom-in. + +[![CAiMIRA UML diagram](classes_UML-CAiMIRA.png)](classes_UML-CAiMIRA.png) + +CAiMIRA `models.py` file UML diagram. \ No newline at end of file diff --git a/caimira/docs/mkdocs/docs/code_documentation/rest_api.md b/caimira/docs/mkdocs/docs/code/rest_api.md similarity index 93% rename from caimira/docs/mkdocs/docs/code_documentation/rest_api.md rename to caimira/docs/mkdocs/docs/code/rest_api.md index 7839bb94..9026afe2 100644 --- a/caimira/docs/mkdocs/docs/code_documentation/rest_api.md +++ b/caimira/docs/mkdocs/docs/code/rest_api.md @@ -1,6 +1,6 @@ # CAiMIRA REST API -The API enables third-party applications to interact with the CAiMIRA [backend](https://gitlab.cern.ch/caimira/caimira), making integration easier and more flexible. This page covers the CAiMIRA [package structure](#directory-layout-key-components), [API usage](#rest-api-overview), [deployment processes](#deployment-process), including versioning guidelines. +The API enables third-party applications to interact with the CAiMIRA [backend](https://gitlab.cern.ch/caimira/caimira), making integration easier and more flexible. This page covers the CAiMIRA [package structure](#directory-layout-key-components) and [API usage](#rest-api-overview). ## Package Overview @@ -201,24 +201,4 @@ As the project is growing, more endpoints targeted to specific tasks will be dev "room_capacity": "10", "room_volume": "60", "total_people": "2" - }' - -## Deployment Process - -The deployment process varies depending on whether changes are pushed to branches, tags, or the test environment (`live/caimira-test` branch). - -### Branch and Tag-based Deployment - -For branch pushes: - -* All branches (except `live/caimira-test`) trigger the **test** stage in the CI/CD pipeline, ensuring the code passes all necessary tests before it is deployed. - -For tag creation: - -* When a new tag is created, the pipeline skips the previous tests, and it builds `Docker` images, storing them in GitLab's container registry. The images can be manually deployed to the OKD platform for the `PROD` - production environment. - -### OKD Platform Deployment -The `cern_caimira` package, which contains the CERN-specific UI, is deployed directly to the OKD platform. The `caimira package`, which contains the backend logic, is deployed as a standalone API for integration with external services. - -### Versioning and Tags -The repository follows a *semantic versioning* scheme, with tags named according to the `MAJOR.MINOR.PATCH` format (e.g., `v5.0.0`). + }' \ No newline at end of file diff --git a/caimira/docs/mkdocs/docs/index.md b/caimira/docs/mkdocs/docs/index.md index 525ff34d..a25767e6 100644 --- a/caimira/docs/mkdocs/docs/index.md +++ b/caimira/docs/mkdocs/docs/index.md @@ -6,16 +6,18 @@ It includes details on the diameter-dependent mathematical model and the code de # Contents: -* [Project Overview]() - * [About](project_overview/about.md) - * [Installation](project_overview/installation.md) - * [Deployment](project_overview/deployment.md) - * [User Guide]() - * [Quick Guide](project_overview/user_guide/quick_guide.md) - * [Full Guide](project_overview/user_guide/full_guide.md) - * [Open Source Acknowledgments](project_overview/open_source_acknowledgments.md) - -* [Code Documentation]() - * [Diameter Normalization](code_documentation/diameter_normalization.md) - * [REST API](code_documentation/rest_api.md) - * [Models Module](code_documentation/models.md) \ No newline at end of file +* [About](root/about.md) +* [Installation](root/installation.md) +* [Deployment](root/deployment.md) +* [Open Source Acknowledgments](root/open_source_acknowledgments.md) +* [License](LICENSE.md) +* [Physics of the model](root/physics_model.md) +* **Code** + * [Architecture](code/architecture.md) + * [models.py](code/models.md) + * [REST API](code/rest_api.md) +* **User Interfaces** + * **CAiMIRA Calculator** + * [Quick Guide](user_interfaces/CAiMIRA/quick_guide.md) + * [Full Guide](user_interfaces/CAiMIRA/full_guide.md) + * [ARIA](https://partnersplatform.who.int/aria) diff --git a/caimira/docs/mkdocs/docs/project_overview/about.md b/caimira/docs/mkdocs/docs/root/about.md similarity index 85% rename from caimira/docs/mkdocs/docs/project_overview/about.md rename to caimira/docs/mkdocs/docs/root/about.md index 32a773a3..69a0c2f0 100644 --- a/caimira/docs/mkdocs/docs/project_overview/about.md +++ b/caimira/docs/mkdocs/docs/root/about.md @@ -47,27 +47,28 @@ As a result, WHO has invited CERN to become a member of a multidisciplinary expe The collaboration takes place within CERNs wide-ranging engagement with other international organisations, promoting shared solutions to societal challenges. ## Authors -CAiMIRA was developed by the following members of CERN - European Council for Nuclear Research (visit [https://home.cern/](https://home.cern/)) and WHO - World Health Organization: -Andre Henriques1, Luis Aleixo1, Marco Andreini1, Gabriella Azzopardi2, James Devine3, Philip Elson4, Nicolas Mounet2, Markus Kongstein Rognlien2,6, Nicola Tarocco5, Luca Fontana7, Alice Simniceanu7 +Andre Henriques1,2, Wei Jia3, Luis Aleixo1, Nicolas Mounet1, Luca Fontana4,5, Alice Simniceanu2,6, James Devine1, Philip Elson1, Gabriella Azzopardi1, Markus Kongstein Rognlien1,7, Marco Andreini1, Nicola Tarocco1, Olivia Keiser2, Yugou Li3, Julian Tang8 -1HSE Unit, Occupational Health & Safety Group, CERN
-2Beams Department, Accelerators and Beam Physics Group, CERN
-3Experimental Physics Department, Safety Office, CERN
-4Beams Department, Controls Group, CERN
-5Information Technology Department, Collaboration, Devices & Applications Group, CERN
-6Norwegian University of Science and Technology (NTNU)
-7World Health Organization (WHO)
+1CERN (European Organization for Nuclear Research), Geneva, Switzerland
+2Institute of Global Health, University of Geneva, Geneva, Switzerland
+3Department of Mechanical Engineering, University of Hong Kong, Hong Kong SAR, China
+4Strategic Health Operations, Operations Support and Logistic, Health Emergencies Programme, World Health Organization, Geneva, Switzerland
+5Department of Civil and Mechanical Engineering, Università degli studi di Cassino e del Lazio Meridionale (UNICAS), Cassino, Italy
+6Epidemic and Pandemic Preparedness, Health Emergencies Programme, World Health Organization, Geneva, Switzerland
+7Norwegian University of Science and Technology (NTNU), Torgarden, Norway
+8Respiratory Sciences, University of Leicester, Leicester, UK
#### Other contributors -Anna Efimova1,2, Anel Massalimova1,3, Cole Austin Coughlin1,4, Germain Personne5 +Anna Efimova1,2, Anel Massalimova1,3, Cole Austin Coughlin1,4, Germain Personne5, Matteo Manzinello6, Elias Sandner1 -1Summer Student Programme, CERN
+1CERN
2M.V. Lomonosov Moscow State University
3National Research Nuclear University "MEPhI"
4University of Manitoba
5Université Clermont Auvergne
+6World Health Organization (WHO)
## Reference and Citation diff --git a/caimira/docs/mkdocs/docs/project_overview/deployment.md b/caimira/docs/mkdocs/docs/root/deployment.md similarity index 84% rename from caimira/docs/mkdocs/docs/project_overview/deployment.md rename to caimira/docs/mkdocs/docs/root/deployment.md index 457680d7..82780431 100644 --- a/caimira/docs/mkdocs/docs/project_overview/deployment.md +++ b/caimira/docs/mkdocs/docs/root/deployment.md @@ -138,3 +138,22 @@ but it may be origin if you haven't configured it differently): git push --force upstream name-of-local-branch:live/caimira-test +## Deployment Process + +The deployment process varies depending on whether changes are pushed to branches, tags, or the test environment (`live/caimira-test` branch). + +### Branch and Tag-based Deployment + +For branch pushes: + +* All branches (except `live/caimira-test`) trigger the **test** stage in the CI/CD pipeline, ensuring the code passes all necessary tests before it is deployed. + +For tag creation: + +* When a new tag is created, the pipeline skips the previous tests, and it builds `Docker` images, storing them in GitLab's container registry. The images can be manually deployed to the OKD platform for the `PROD` - production environment. + +### OKD Platform Deployment +The `cern_caimira` package, which contains the CERN-specific UI, is deployed directly to the OKD platform. The `caimira package`, which contains the backend logic, is deployed as a standalone API for integration with external services. + +### Versioning and Tags +The repository follows a *semantic versioning* scheme, with tags named according to the `MAJOR.MINOR.PATCH` format (e.g., `v5.0.0`). diff --git a/caimira/docs/mkdocs/docs/project_overview/installation.md b/caimira/docs/mkdocs/docs/root/installation.md similarity index 98% rename from caimira/docs/mkdocs/docs/project_overview/installation.md rename to caimira/docs/mkdocs/docs/root/installation.md index 1c579785..e0e9ae34 100644 --- a/caimira/docs/mkdocs/docs/project_overview/installation.md +++ b/caimira/docs/mkdocs/docs/root/installation.md @@ -134,7 +134,7 @@ The response format will be: } ``` -For further details please refer to the [REST API documentation page](../code_documentation/rest_api.md). +For further details please refer to the [REST API documentation page](../code/rest_api.md). #### Running the Expert-Apps @@ -217,7 +217,7 @@ To compile and view CAiMIRA's documentation, follow these steps: Run the `style_docs.py` script to apply custom styles, move required files, and generate a UML diagram: python style_docs.py \ - && mv sphinx/_build/markdown/index.md mkdocs/docs/code_documentation/models.md \ + && mv sphinx/_build/markdown/index.md mkdocs/docs/code/models.md \ && pyreverse -o png -p UML-CAiMIRA --output-directory mkdocs/docs ../src/caimira/calculator/models/models.py 4. Start the documentation server diff --git a/caimira/docs/mkdocs/docs/project_overview/open_source_acknowledgments.md b/caimira/docs/mkdocs/docs/root/open_source_acknowledgments.md similarity index 100% rename from caimira/docs/mkdocs/docs/project_overview/open_source_acknowledgments.md rename to caimira/docs/mkdocs/docs/root/open_source_acknowledgments.md diff --git a/caimira/docs/mkdocs/docs/code_documentation/diameter_normalization.md b/caimira/docs/mkdocs/docs/root/physics_model.md similarity index 98% rename from caimira/docs/mkdocs/docs/code_documentation/diameter_normalization.md rename to caimira/docs/mkdocs/docs/root/physics_model.md index 45865af5..4fc4e1d1 100644 --- a/caimira/docs/mkdocs/docs/code_documentation/diameter_normalization.md +++ b/caimira/docs/mkdocs/docs/root/physics_model.md @@ -1,6 +1,6 @@ -# Diameter-dependent Model +# Physics of the 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. +This page describes the CAiMIRA model and its dependence on the Particles diameter. ## Context @@ -304,16 +304,6 @@ Note still that nothing depends on the aerosol diameter $D$ in this case (no par Since the CO2 concentration differs from the virus concentration, the specific removal rate, CO2 atmospheric concentration and normalization factors are respectively defined in `caimira.models.models.CO2ConcentrationModel.removal_rate()`, `caimira.models.models.CO2ConcentrationModel.min_background_concentration()` and `caimira.models.models.CO2ConcentrationModel.normalization_factor()`. - - -## CAiMIRA UML Diagram - -The following diagram describes all the data classes and their relations under the models.py file. Click the diagram to zoom-in. - -[![CAiMIRA UML diagram](classes_UML-CAiMIRA.png)](classes_UML-CAiMIRA.png) - -CAiMIRA `models.py` file UML diagram. - ## References * **[1]** Jia, Wei, et al. “Exposure and respiratory infection risk via the short-range airborne route.” Building and environment 219 (2022): 109166. [doi.org/10.1016/j.buildenv.2022.109166](https://doi.org/10.1016/j.buildenv.2022.109166) diff --git a/caimira/docs/mkdocs/docs/project_overview/user_guide/full_guide.md b/caimira/docs/mkdocs/docs/user_interfaces/CAiMIRA/full_guide.md similarity index 99% rename from caimira/docs/mkdocs/docs/project_overview/user_guide/full_guide.md rename to caimira/docs/mkdocs/docs/user_interfaces/CAiMIRA/full_guide.md index c97bd73d..54f82058 100644 --- a/caimira/docs/mkdocs/docs/project_overview/user_guide/full_guide.md +++ b/caimira/docs/mkdocs/docs/user_interfaces/CAiMIRA/full_guide.md @@ -1,4 +1,4 @@ -## CAiMIRA Calculator +## [CAiMIRA Calculator](https://caimira.web.cern.ch/) This guide helps on how to use the calculator app. For more information on the Airborne Transmission of SARS-CoV-2, feel free to check out the HSE Seminar: [https://cds.cern.ch/record/2743403](https://cds.cern.ch/record/2743403) diff --git a/caimira/docs/mkdocs/docs/project_overview/user_guide/img/window_opening.png b/caimira/docs/mkdocs/docs/user_interfaces/CAiMIRA/img/window_opening.png similarity index 100% rename from caimira/docs/mkdocs/docs/project_overview/user_guide/img/window_opening.png rename to caimira/docs/mkdocs/docs/user_interfaces/CAiMIRA/img/window_opening.png diff --git a/caimira/docs/mkdocs/docs/project_overview/user_guide/img/window_type.PNG b/caimira/docs/mkdocs/docs/user_interfaces/CAiMIRA/img/window_type.PNG similarity index 100% rename from caimira/docs/mkdocs/docs/project_overview/user_guide/img/window_type.PNG rename to caimira/docs/mkdocs/docs/user_interfaces/CAiMIRA/img/window_type.PNG diff --git a/caimira/docs/mkdocs/docs/project_overview/user_guide/quick_guide.md b/caimira/docs/mkdocs/docs/user_interfaces/CAiMIRA/quick_guide.md similarity index 98% rename from caimira/docs/mkdocs/docs/project_overview/user_guide/quick_guide.md rename to caimira/docs/mkdocs/docs/user_interfaces/CAiMIRA/quick_guide.md index c12b51ac..f80e91ea 100644 --- a/caimira/docs/mkdocs/docs/project_overview/user_guide/quick_guide.md +++ b/caimira/docs/mkdocs/docs/user_interfaces/CAiMIRA/quick_guide.md @@ -1,4 +1,4 @@ -## CAiMIRA Calculator +## [CAiMIRA Calculator](https://caimira.web.cern.ch/) This tool simulates the airborne spread of SARS-CoV-2 virus in a finite volume and estimates the risk of COVID-19 infection. It is based on current scientific data and can be used to compare the effectiveness of different mitigation measures. diff --git a/caimira/docs/mkdocs/mkdocs.yml b/caimira/docs/mkdocs/mkdocs.yml index e426338a..70b461a2 100644 --- a/caimira/docs/mkdocs/mkdocs.yml +++ b/caimira/docs/mkdocs/mkdocs.yml @@ -4,19 +4,21 @@ theme: nav: - Home: index.md - - Project Overview: - - About: project_overview/about.md - - Installation: project_overview/installation.md - - Deployment: project_overview/deployment.md - - User Guide: - - Quick Guide: project_overview/user_guide/quick_guide.md - - Full Guide: project_overview/user_guide/full_guide.md - - Open Source Acknowledgments: project_overview/open_source_acknowledgments.md - - License: LICENSE.md - - Code Documentation: - - Diameter Normalization: code_documentation/diameter_normalization.md - - REST API: code_documentation/rest_api.md - - Models Module: code_documentation/models.md + - About: root/about.md + - Installation: root/installation.md + - Deployment: root/deployment.md + - Open Source Acknowledgments: root/open_source_acknowledgments.md + - License: LICENSE.md + - Physics of the model: root/physics_model.md + - Code: + - Architecture: code/architecture.md + - models.py: code/models.md + - REST API: code/rest_api.md + - User Interfaces: + - CAiMIRA Calculator: + - Quick Guide: user_interfaces/CAiMIRA/quick_guide.md + - Full Guide: user_interfaces/CAiMIRA/full_guide.md + - ARIA: https://partnersplatform.who.int/aria markdown_extensions: - pymdownx.arithmatex: diff --git a/caimira/docs/style_docs.py b/caimira/docs/style_docs.py index 0cfc99fd..d278d728 100644 --- a/caimira/docs/style_docs.py +++ b/caimira/docs/style_docs.py @@ -199,7 +199,7 @@ def main(): print(f"File '{index_file_path}' does not exist, skipping update.") # Path to the open source acknowledgements markdown file to be updated - acknowledgements_file_path = 'mkdocs/docs/project_overview/open_source_acknowledgments.md' + acknowledgements_file_path = 'mkdocs/docs/root/open_source_acknowledgments.md' if os.path.isfile(acknowledgements_file_path): # Retrieve package details @@ -209,7 +209,7 @@ def main(): add_python_dependencies_section(acknowledgements_file_path, package_details) # Generate the pie chart - output_image_path = 'mkdocs/docs/project_overview/license_distribution.png' + output_image_path = 'mkdocs/docs/root/license_distribution.png' generate_license_distribution_pie_chart(package_details, output_image_path) else: print(f"File '{acknowledgements_file_path}' does not exist, skipping update.")