From 6b3efb9345fa07854ec98d55d9eeacca7df035f1 Mon Sep 17 00:00:00 2001 From: Nicola Tarocco Date: Mon, 21 Oct 2024 23:24:16 +0200 Subject: [PATCH 1/8] releases: add PyPI config - closes #430 --- .gitlab-ci.yml | 23 ++++ caimira/docs/mkdocs/docs/code/rest_api.md | 26 ++-- caimira/docs/mkdocs/docs/root/installation.md | 126 +++++++++++------- caimira/pyproject.toml | 2 +- .../calculator/report/virus_report_data.py | 2 +- cern_caimira/pyproject.toml | 1 - 6 files changed, 118 insertions(+), 62 deletions(-) diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 69624f7b..6424a9cb 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -206,6 +206,7 @@ docker-build-docs-release: # ################################################################################################### # Deploy to OpenShift + .deploy: stage: deploy image: gitlab-registry.cern.ch/paas-tools/openshift-client @@ -249,3 +250,25 @@ deploy-docs-test: IMAGE_NAME: caimira-docs OPENSHIFT_DEPLOYMENT: caimira-test-docs OPENSHIFT_CONTAINER_NAME: caimira-test-docs + +# ################################################################################################### +# Publish on PyPI + +.publish-to-pypi: + stage: deploy + image: python:3.12 + script: + - cd caimira + - pip install build twine + - python -m build + - twine upload dist/* -u $PYPI_USERNAME -p $PYPI_TOKEN + rules: + - if: $CI_COMMIT_TAG + +publish-caimira: + extends: .publish-to-pypi + variables: + PYPI_USERNAME: __token__ + PYPI_TOKEN: $PYPI_TOKEN + rules: + - if: $CI_COMMIT_TAG diff --git a/caimira/docs/mkdocs/docs/code/rest_api.md b/caimira/docs/mkdocs/docs/code/rest_api.md index a0222710..e24425bc 100644 --- a/caimira/docs/mkdocs/docs/code/rest_api.md +++ b/caimira/docs/mkdocs/docs/code/rest_api.md @@ -46,17 +46,25 @@ The API is served by the **Tornado** web framework, which provides asynchronous To run the API, follow these steps from the root directory of the project: -1. Install dependencies: - ``` - cd caimira - pip install -e . - ``` +1. Install dependencies (two options available): + - From previously cloned [GitLab Repository](https://gitlab.cern.ch/caimira/caimira): + + cd caimira + pip install -e . + + - From [PyPI](https://pypi.org/project/caimira/): + + pip install --index-url https://test.pypi.org/simple --extra-index-url https://pypi.org/simple caimira + + !!! info + `--extra-index-url` is necessary to resolve dependencies from PyPI. + 2. Run the backend: - ``` - python -m caimira.api.app - ``` - The web server will be accessible on port `8081`. + + python -m caimira.api.app + + The web server will be accessible at [http://localhost:8081/](http://localhost:8081/). #### API Endpoints diff --git a/caimira/docs/mkdocs/docs/root/installation.md b/caimira/docs/mkdocs/docs/root/installation.md index e41215b5..f835eb57 100644 --- a/caimira/docs/mkdocs/docs/root/installation.md +++ b/caimira/docs/mkdocs/docs/root/installation.md @@ -3,7 +3,7 @@ This installation guide provides instructions for both quickly running CAiMIRA w **Guide Overview**: 1. **[Quick Start](#quick-start)**: Designed for users aiming to run CAiMIRA with minimal setup. The Quick Guide section outlines the fastest approach to using CAiMIRA through a pre-built Docker image. -2. **[Development Installation](#development-installation)**: Intended for developers or those requiring advanced customization. This section includes detailed steps for setting up the environment, running the backend REST API, and contributing to the project. +2. **[Development Installation](#development-installation)**: Intended for developers or those requiring advanced customization. This section includes detailed steps for setting up the environment, running the backend REST API, customizing the UI, and contributing to the project. ## Quick Start @@ -37,7 +37,7 @@ This will start a local version of CAiMIRA, which can be visited by loading this This section provides comprehensive instructions for setting up the CAiMIRA environment in development mode. The guide is tailored for contributors and advanced users who want to build the project from source, customize its features, or contribute to its codebase1. -Developers can follow the steps below to build and run the CAiMIRA backend and frontend applications, set up APIs, run tests, and generate the documentation. Additionally, this section includes instructions for running legacy expert applications, profiling the system, and testing specific features. +Developers can follow the steps below to build and run the CAiMIRA backend, APIs, or Calculator applications, run tests, and generate the documentation. Additionally, this section includes instructions for running legacy expert applications, profiling the system, and testing specific features. The project contains two different Python packages: @@ -62,8 +62,8 @@ Before proceeding with the development installation of CAiMIRA, ensure that your python -m pip install --upgrade pip setuptools - !!! note - It's recommended to use `pyenv` or similar tools to manage Python versions. For details on how to install and use `pyenv`, see [here](https://github.com/pyenv/pyenv). While not mandatory, it is also recommended to create a virtual environment (`virtualenv`) to avoid conflicts between different package versions. For more information on setting up a virtual environment, see [here](https://virtualenv.pypa.io/en/latest/). + !!! note + It's recommended to use `pyenv` or similar tools to manage Python versions. For details on how to install and use `pyenv`, see [here](https://github.com/pyenv/pyenv). While not mandatory, it is also recommended to create a virtual environment (`virtualenv`) to avoid conflicts between different package versions. For more information on setting up a virtual environment, see [here](https://virtualenv.pypa.io/en/latest/). 2. **Git**: @@ -79,32 +79,87 @@ Before proceeding with the development installation of CAiMIRA, ensure that your - A code editor such as [VSCode](https://code.visualstudio.com/), or an IDE like [PyCharm](https://www.jetbrains.com/pycharm/). -5. **Repository Setup**: - - - Clone the CAiMIRA repository from the GitLab or GitHub mirror by opening a terminal and running: - - git clone https://gitlab.cern.ch/caimira/caimira.git - cd caimira - - !!! note - The directory in which you run the previous commands will be the root directory of your project. - ### Installing and running -This section provides instructions for setting up, running, and testing CAiMIRA in a local development environment. It covers the installation of the backend logic, interaction with user interfaces, and utilization of the API app. Additionally, instructions for legacy applications (expert apps), testing procedures, and tools for profiling and documentation generation are provided. +This section provides instructions for setting up, running, and testing CAiMIRA in a local development environment. It covers the installation of the backend logic, interaction with the CAiMIRA-native UI, and utilization of the API app. Additionally, instructions for legacy applications (expert apps), testing procedures, and tools for profiling and documentation generation are provided. ##### Prerequisites: -After following what is described in the main [prerequisites](#prerequisites) section, ensure the following dependencies are correctly installed: +!!! warning + Follow this section only if you are not proceeding to the [CAiMIRA backend](#1-backend) chapter. -1. **CAiMIRA repository**: Can be cloned from the official GitLab repository [here](https://gitlab.cern.ch/caimira/caimira). -2. **Python `3.9` or later**: Required for running the CAiMIRA backend and UI. +1. Ensure the tools listed in the main prerequisites are installed. +2. Clone the CAiMIRA repository and install dependencies: + + git clone https://gitlab.cern.ch/caimira/caimira.git + cd caimira + + !!! note + The directory in which you run the previous commands will be the root directory of your project. #### CAiMIRA -CAiMIRA can be installed locally for development and usage in editable mode. This allows full access to both the backend logic, as well as the CAiMIRA-native UI. The following sections provide step-by-step instructions for installing and running CAiMIRA on a local environment. +The following sections provide step-by-step instructions for setting up and running [CAiMIRA backend](#1-backend), [CAiMIRA Calculator](#2-calculator) and associated applications in a local development environment. It is designed for users seeking to develop new features, test existing functionalities, or explore the available tools. + +##### 1. Backend + +The CAiMIRA backend includes the mathematical logic and the REST API for programmatic interaction with the models. Local installation enables full access to these features, supporting development and testing. + +###### Installing + +CAiMIRA's backend logic can be installed with the following two options: + +1. **From the [GitLab Repository](https://gitlab.cern.ch/caimira/caimira)**: + + Clone the repository and install it in editable mode for development by running the following commands: + + git clone https://gitlab.cern.ch/caimira/caimira.git + cd caimira + pip install -e ./caimira + +2. **From [PyPI](https://pypi.org/project/caimira/)**: + + CAiMIRA is available on PyPI for installation. For testing new releases, use the PyPI Test instance by running the following command (directory independent): + + pip install --index-url https://test.pypi.org/simple --extra-index-url https://pypi.org/simple caimira + + !!! info + `--extra-index-url` is necessary to resolve dependencies from PyPI. + +###### Running and testing + +CAiMIRA backend includes a REST API for programmatic interaction with its models. The following steps describe how to run and test the API locally. + +1. **Run the backend API**: + + python -m caimira.api.app + + The Tornado server will be accessible at [http://localhost:8081/](http://localhost:8081/). + +2. **Test the API**: + + Send a `POST` request to `http://localhost:8081/virus_report` with the required inputs in the body. Example request formats can be found in the [Virus Validator Code](https://gitlab.cern.ch/caimira/caimira/blob/master/caimira/src/caimira/calculator/validators/virus/virus_validator.py#L565). -##### Installing: +3. **Example Response**: + A successful response will return data in the following format: + + !!! success + { + "status": "success", + "message": "Results generated successfully", + "report_data": { + ... + }, + ... + } + + For further details please refer to the [REST API documentation page](../code/rest_api.md). + +##### 2. Calculator + +The CAiMIRA Calculator integrates the backend functionality with a CAiMIRA-native UI, offering a complete webpage for modeling and interaction. Local installation in editable mode facilitates both development and testing, which are described in the following sections. + +###### Installing: In order to install the CAiMIRA's backend logic, from the root directory of the project, run: @@ -116,7 +171,7 @@ In order to install the CAiMIRA-native UI version, that links to the previously cd cern_caimira pip install -e . -##### Running: +###### Running: The calculator can be started with the CAiMIRA-native UI using the following command in the project root directory: @@ -171,35 +226,6 @@ These applications only work within Jupyter notebooks. Attempting to run them ou - Open the notebook (e.g. `caimira/apps/expert/caimira.ipynb`) and run the cells by clicking the `run` button next to each cell. -##### API app - -CAiMIRA includes a REST API for programmatic interaction with its models. The following steps describe how to run and test the API locally. - -1. **Run the backend API**: - - python -m caimira.api.app - - The Tornado server will be accessible on port `8081`. - -2. **Test the API**: - - Send a `POST` request to `http://localhost:8081/virus_report` with the required inputs in the body. Example request formats can be found in the [Virus Validator Code](https://gitlab.cern.ch/caimira/caimira/blob/master/caimira/src/caimira/calculator/validators/virus/virus_validator.py#L565). - -3. **Example Response**: - A successful response will return data in the following format: - - !!! success - { - "status": "success", - "message": "Results generated successfully", - "report_data": { - ... - }, - ... - } - - For further details please refer to the [REST API documentation page](../code/rest_api.md). - #### Tests CAiMIRA includes a suite of tests to validate the functionality of both its backend (`caimira` package) and UI components (`cern_caimira` package). diff --git a/caimira/pyproject.toml b/caimira/pyproject.toml index e1188fd6..40d99c1e 100644 --- a/caimira/pyproject.toml +++ b/caimira/pyproject.toml @@ -6,6 +6,7 @@ build-backend = "setuptools.build_meta" name = "caimira" version = "4.17.5" description = "CAiMIRA - CERN Airborne Model for Indoor Risk Assessment" +readme = "README.md" license = { text = "Apache-2.0" } authors = [ { name = "Andre Henriques", email = "andre.henriques@cern.ch" } @@ -41,7 +42,6 @@ test = [ "pytest-mypy >= 0.10.3", "mypy >= 1.0.0", "pytest-tornasync", - "numpy-stubs @ git+https://github.com/numpy/numpy-stubs.git", "types-dataclasses", "types-python-dateutil", "types-requests", diff --git a/caimira/src/caimira/calculator/report/virus_report_data.py b/caimira/src/caimira/calculator/report/virus_report_data.py index 6c4d62e6..2071fb2a 100644 --- a/caimira/src/caimira/calculator/report/virus_report_data.py +++ b/caimira/src/caimira/calculator/report/virus_report_data.py @@ -220,7 +220,7 @@ def calculate_report_data(form: VirusFormData, executor_factory: typing.Callable def conditional_prob_inf_given_vl_dist( infection_probability: models._VectorisedFloat, viral_loads: np.ndarray, - specific_vl: float, + specific_vl: models._VectorisedFloat, step: models._VectorisedFloat ): diff --git a/cern_caimira/pyproject.toml b/cern_caimira/pyproject.toml index ecb8c8da..13d5aff1 100644 --- a/cern_caimira/pyproject.toml +++ b/cern_caimira/pyproject.toml @@ -43,7 +43,6 @@ test = [ "pytest-mypy >= 0.10.3", "mypy >= 1.0.0", "pytest-tornasync", - "numpy-stubs @ git+https://github.com/numpy/numpy-stubs.git", "types-dataclasses", "types-requests" ] From 987ad74531ae68dc4b4ebe8d62ae048477cb7a6f Mon Sep 17 00:00:00 2001 From: Andre Henriques Date: Sat, 30 Nov 2024 21:30:30 +0100 Subject: [PATCH 2/8] suggestions for installation.md --- caimira/docs/mkdocs/docs/root/installation.md | 65 ++++++++----------- 1 file changed, 28 insertions(+), 37 deletions(-) diff --git a/caimira/docs/mkdocs/docs/root/installation.md b/caimira/docs/mkdocs/docs/root/installation.md index f835eb57..5ef75169 100644 --- a/caimira/docs/mkdocs/docs/root/installation.md +++ b/caimira/docs/mkdocs/docs/root/installation.md @@ -81,21 +81,7 @@ Before proceeding with the development installation of CAiMIRA, ensure that your ### Installing and running -This section provides instructions for setting up, running, and testing CAiMIRA in a local development environment. It covers the installation of the backend logic, interaction with the CAiMIRA-native UI, and utilization of the API app. Additionally, instructions for legacy applications (expert apps), testing procedures, and tools for profiling and documentation generation are provided. - -##### Prerequisites: - -!!! warning - Follow this section only if you are not proceeding to the [CAiMIRA backend](#1-backend) chapter. - -1. Ensure the tools listed in the main prerequisites are installed. -2. Clone the CAiMIRA repository and install dependencies: - - git clone https://gitlab.cern.ch/caimira/caimira.git - cd caimira - - !!! note - The directory in which you run the previous commands will be the root directory of your project. +This section provides instructions for setting up, running, and testing CAiMIRA in a local development environment. It covers the installation of the backend logic alone (e.g. for parametric studies, modelling, research), interaction with the CAiMIRA-native UI, and utilization of the API app. Additionally, instructions for legacy applications (expert apps), testing procedures, and tools for profiling and documentation generation are provided. #### CAiMIRA @@ -103,30 +89,36 @@ The following sections provide step-by-step instructions for setting up and runn ##### 1. Backend -The CAiMIRA backend includes the mathematical logic and the REST API for programmatic interaction with the models. Local installation enables full access to these features, supporting development and testing. - -###### Installing +The CAiMIRA backend includes the logic underlying the [physics model](https://caimira-test.docs.cern.ch/root/physics_model/) and the REST API for programmatic interaction with the models. Local installation enables full access to these features, supporting development and testing. CAiMIRA's backend logic can be installed with the following two options: -1. **From the [GitLab Repository](https://gitlab.cern.ch/caimira/caimira)**: - - Clone the repository and install it in editable mode for development by running the following commands: - - git clone https://gitlab.cern.ch/caimira/caimira.git - cd caimira - pip install -e ./caimira - -2. **From [PyPI](https://pypi.org/project/caimira/)**: +1. **From [PyPI](https://pypi.org/project/caimira/)**: - CAiMIRA is available on PyPI for installation. For testing new releases, use the PyPI Test instance by running the following command (directory independent): + pip install caimira + + !!! note + The directory in which you run these commands will be the root directory of your project. + + For testing new releases, use the PyPI Test instance by running the following command (directory independent): pip install --index-url https://test.pypi.org/simple --extra-index-url https://pypi.org/simple caimira !!! info `--extra-index-url` is necessary to resolve dependencies from PyPI. -###### Running and testing +2. **From the [GitLab Repository](https://gitlab.cern.ch/caimira/caimira)**: + + Clone the repository and install it in editable mode for development by running the following commands: + + git clone https://gitlab.cern.ch/caimira/caimira.git + + In the root directory: + + cd caimira + pip install -e ./caimira + +###### Running and testing with API CAiMIRA backend includes a REST API for programmatic interaction with its models. The following steps describe how to run and test the API locally. @@ -155,16 +147,11 @@ CAiMIRA backend includes a REST API for programmatic interaction with its models For further details please refer to the [REST API documentation page](../code/rest_api.md). -##### 2. Calculator +##### 2. Native Calculator app The CAiMIRA Calculator integrates the backend functionality with a CAiMIRA-native UI, offering a complete webpage for modeling and interaction. Local installation in editable mode facilitates both development and testing, which are described in the following sections. -###### Installing: - -In order to install the CAiMIRA's backend logic, from the root directory of the project, run: - - cd caimira - pip install -e . +###### Installing UI: In order to install the CAiMIRA-native UI version, that links to the previously installed backend, from the root directory of the project, run: @@ -185,6 +172,10 @@ Additional options allow customization, such as specifying themes, application r python -m cern_caimira.apps.calculator --theme=cern_caimira/src/cern_caimira/apps/templates/{theme} + Where `{theme}` is the name of the folder within the `cern_caimira/apps/templates/` directory. E.g. for the `cern` theme: + + python -m cern_caimira.apps.calculator --theme=cern_caimira/src/cern_caimira/apps/templates/cern + - **Run the app with a different `APPLICATION_ROOT` path**: The base path of the web application on the server. It determines where the app is "rooted" in relation to the server's URL structure. To run with a specific application root: @@ -201,7 +192,7 @@ Each of these commands will start a local version of CAiMIRA, which can be visit ##### Expert-Apps: -The CAiMIRA Expert App and CO2 App are legacy tools designed to provide dynamic interaction with the CAiMIRA model parameters. +The CAiMIRA Expert App and CO~2~ App are legacy tools designed to provide dynamic interaction with the CAiMIRA model parameters. !!! warning From a2c76d855138fa41006561c155597757fe270851 Mon Sep 17 00:00:00 2001 From: lrdossan Date: Mon, 2 Dec 2024 11:33:43 +0100 Subject: [PATCH 3/8] updated copyright --- README.md | 2 +- caimira/LICENSE | 2 +- caimira/README.md | 2 +- caimira/docs/mkdocs/docs/LICENSE.md | 2 +- caimira/docs/mkdocs/docs/root/about.md | 2 +- cern_caimira/LICENSE | 2 +- cern_caimira/README.md | 2 +- cern_caimira/src/cern_caimira/apps/templates/base/index.html.j2 | 2 +- 8 files changed, 8 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index b8857f87..ce160e3c 100644 --- a/README.md +++ b/README.md @@ -38,7 +38,7 @@ Contributions are welcome on our [GitHub repository](https://github.com/CERN/CAi Developed by CERN's HSE, Beams, and IT departments, in collaboration with WHO. -© Copyright 2020-2021 CERN. All rights not expressly granted are reserved.
+© Copyright 2020 CERN. All rights not expressly granted are reserved.
Licensed under the Apache License, Version 2.0 See the full [license](caimira/LICENSE) for details. diff --git a/caimira/LICENSE b/caimira/LICENSE index de49c2af..97f01f2d 100644 --- a/caimira/LICENSE +++ b/caimira/LICENSE @@ -1,4 +1,4 @@ -Copyright 2020-2021 CERN. All rights not expressly granted are reserved. +Copyright 2020 CERN. All rights not expressly granted are reserved. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. diff --git a/caimira/README.md b/caimira/README.md index b8857f87..ce160e3c 100644 --- a/caimira/README.md +++ b/caimira/README.md @@ -38,7 +38,7 @@ Contributions are welcome on our [GitHub repository](https://github.com/CERN/CAi Developed by CERN's HSE, Beams, and IT departments, in collaboration with WHO. -© Copyright 2020-2021 CERN. All rights not expressly granted are reserved.
+© Copyright 2020 CERN. All rights not expressly granted are reserved.
Licensed under the Apache License, Version 2.0 See the full [license](caimira/LICENSE) for details. diff --git a/caimira/docs/mkdocs/docs/LICENSE.md b/caimira/docs/mkdocs/docs/LICENSE.md index de49c2af..97f01f2d 100644 --- a/caimira/docs/mkdocs/docs/LICENSE.md +++ b/caimira/docs/mkdocs/docs/LICENSE.md @@ -1,4 +1,4 @@ -Copyright 2020-2021 CERN. All rights not expressly granted are reserved. +Copyright 2020 CERN. All rights not expressly granted are reserved. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. diff --git a/caimira/docs/mkdocs/docs/root/about.md b/caimira/docs/mkdocs/docs/root/about.md index 69a0c2f0..196eefef 100644 --- a/caimira/docs/mkdocs/docs/root/about.md +++ b/caimira/docs/mkdocs/docs/root/about.md @@ -78,7 +78,7 @@ CAiMIRA – CERN Airborne Model for Indoor Risk Assessment tool [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.6520431.svg)](https://doi.org/10.5281/zenodo.6520431) -© Copyright 2020-2021 CERN. All rights not expressly granted are reserved. +© Copyright 2020 CERN. All rights not expressly granted are reserved. **For use of the CAiMIRA model** diff --git a/cern_caimira/LICENSE b/cern_caimira/LICENSE index de49c2af..97f01f2d 100644 --- a/cern_caimira/LICENSE +++ b/cern_caimira/LICENSE @@ -1,4 +1,4 @@ -Copyright 2020-2021 CERN. All rights not expressly granted are reserved. +Copyright 2020 CERN. All rights not expressly granted are reserved. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. diff --git a/cern_caimira/README.md b/cern_caimira/README.md index b8857f87..ce160e3c 100644 --- a/cern_caimira/README.md +++ b/cern_caimira/README.md @@ -38,7 +38,7 @@ Contributions are welcome on our [GitHub repository](https://github.com/CERN/CAi Developed by CERN's HSE, Beams, and IT departments, in collaboration with WHO. -© Copyright 2020-2021 CERN. All rights not expressly granted are reserved.
+© Copyright 2020 CERN. All rights not expressly granted are reserved.
Licensed under the Apache License, Version 2.0 See the full [license](caimira/LICENSE) for details. diff --git a/cern_caimira/src/cern_caimira/apps/templates/base/index.html.j2 b/cern_caimira/src/cern_caimira/apps/templates/base/index.html.j2 index 34bb578d..6d831091 100644 --- a/cern_caimira/src/cern_caimira/apps/templates/base/index.html.j2 +++ b/cern_caimira/src/cern_caimira/apps/templates/base/index.html.j2 @@ -89,7 +89,7 @@
  • CAiMIRA – CERN Airborne Model for Indoor Risk Assessment tool
  • DOI
    - © Copyright 2020-2021 CERN. All rights not expressly granted are reserved.
    + © Copyright 2020 CERN. All rights not expressly granted are reserved.
    Licensed under the Apache License, Version 2.0
    LICENSE
From 640c4c5e28ce04393758adfe1f1db1e27503b9f1 Mon Sep 17 00:00:00 2001 From: lrdossan Date: Mon, 2 Dec 2024 11:33:53 +0100 Subject: [PATCH 4/8] changed project main URL --- caimira/pyproject.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/caimira/pyproject.toml b/caimira/pyproject.toml index 40d99c1e..ff09c40a 100644 --- a/caimira/pyproject.toml +++ b/caimira/pyproject.toml @@ -56,7 +56,7 @@ doc = [ ] [project.urls] -Homepage = "https://github.com/cern/caimira" +Homepage = "https://gitlab.cern.ch/caimira/caimira" [tool.setuptools.package-data] caimira = ["**/*"] From 1eee08dbc9f3a3593d0b22a3cde63ad93655f52c Mon Sep 17 00:00:00 2001 From: lrdossan Date: Mon, 2 Dec 2024 11:34:45 +0100 Subject: [PATCH 5/8] updated installation structure --- caimira/docs/mkdocs/docs/root/installation.md | 150 ++++++++++-------- 1 file changed, 86 insertions(+), 64 deletions(-) diff --git a/caimira/docs/mkdocs/docs/root/installation.md b/caimira/docs/mkdocs/docs/root/installation.md index 5ef75169..24c93421 100644 --- a/caimira/docs/mkdocs/docs/root/installation.md +++ b/caimira/docs/mkdocs/docs/root/installation.md @@ -3,7 +3,7 @@ This installation guide provides instructions for both quickly running CAiMIRA w **Guide Overview**: 1. **[Quick Start](#quick-start)**: Designed for users aiming to run CAiMIRA with minimal setup. The Quick Guide section outlines the fastest approach to using CAiMIRA through a pre-built Docker image. -2. **[Development Installation](#development-installation)**: Intended for developers or those requiring advanced customization. This section includes detailed steps for setting up the environment, running the backend REST API, customizing the UI, and contributing to the project. +2. **[Development Installation](#development-installation)**: Intended for developers or those requiring advanced customization. This section includes detailed steps for setting up the environment, customizing the UI, running the backend REST API, and contributing to the project. ## Quick Start @@ -81,86 +81,45 @@ Before proceeding with the development installation of CAiMIRA, ensure that your ### Installing and running -This section provides instructions for setting up, running, and testing CAiMIRA in a local development environment. It covers the installation of the backend logic alone (e.g. for parametric studies, modelling, research), interaction with the CAiMIRA-native UI, and utilization of the API app. Additionally, instructions for legacy applications (expert apps), testing procedures, and tools for profiling and documentation generation are provided. +This section provides instructions for setting up, running, and testing CAiMIRA in a local development environment. -#### CAiMIRA +Cloning the full repository from GitLab is required for using the [native Calculator app](#calculator), running [tests](#tests), [profiling](#profiler), or generating [documentation](#docs). This ensures access to both the backend and the native UI, along with all tools and resources. -The following sections provide step-by-step instructions for setting up and running [CAiMIRA backend](#1-backend), [CAiMIRA Calculator](#2-calculator) and associated applications in a local development environment. It is designed for users seeking to develop new features, test existing functionalities, or explore the available tools. +The repository can be cloned with the following command: -##### 1. Backend + git clone https://gitlab.cern.ch/caimira/caimira.git + cd caimira -The CAiMIRA backend includes the logic underlying the [physics model](https://caimira-test.docs.cern.ch/root/physics_model/) and the REST API for programmatic interaction with the models. Local installation enables full access to these features, supporting development and testing. - -CAiMIRA's backend logic can be installed with the following two options: - -1. **From [PyPI](https://pypi.org/project/caimira/)**: - - pip install caimira - - !!! note - The directory in which you run these commands will be the root directory of your project. - - For testing new releases, use the PyPI Test instance by running the following command (directory independent): - - pip install --index-url https://test.pypi.org/simple --extra-index-url https://pypi.org/simple caimira - - !!! info - `--extra-index-url` is necessary to resolve dependencies from PyPI. - -2. **From the [GitLab Repository](https://gitlab.cern.ch/caimira/caimira)**: - - Clone the repository and install it in editable mode for development by running the following commands: - - git clone https://gitlab.cern.ch/caimira/caimira.git - - In the root directory: - - cd caimira - pip install -e ./caimira - -###### Running and testing with API - -CAiMIRA backend includes a REST API for programmatic interaction with its models. The following steps describe how to run and test the API locally. - -1. **Run the backend API**: - - python -m caimira.api.app +!!! note + The directory in which you run these commands will be the root directory of your project. - The Tornado server will be accessible at [http://localhost:8081/](http://localhost:8081/). +!!! warning + If only the backend functionality is needed, such as for REST API integration or standalone use, the repository does not necessarily needs to be cloned. Instead, the backend can be installed and run directly using the instructions provided in the [backend](#backend) section. -2. **Test the API**: +#### Calculator - Send a `POST` request to `http://localhost:8081/virus_report` with the required inputs in the body. Example request formats can be found in the [Virus Validator Code](https://gitlab.cern.ch/caimira/caimira/blob/master/caimira/src/caimira/calculator/validators/virus/virus_validator.py#L565). +The following sections provide step-by-step instructions for setting up and running the native CAiMIRA Calculator app and associated applications in a local development environment. It is designed for users seeking to develop new features, test existing functionalities, or explore the available tools. -3. **Example Response**: - A successful response will return data in the following format: +!!! info + The CAiMIRA Calculator integrates the backend functionality with a CAiMIRA-native UI, offering a complete webpage for modeling and interaction. Therefore, local installation of the two packages - [`caimira`](#installing-backend) and [`cern_caimira`](#installing-ui) - in editable mode is required, and are described in the following sections. - !!! success - { - "status": "success", - "message": "Results generated successfully", - "report_data": { - ... - }, - ... - } - - For further details please refer to the [REST API documentation page](../code/rest_api.md). +##### Installing backend -##### 2. Native Calculator app +In order to install the CAiMIRA backend, from the root directory of the project, run: -The CAiMIRA Calculator integrates the backend functionality with a CAiMIRA-native UI, offering a complete webpage for modeling and interaction. Local installation in editable mode facilitates both development and testing, which are described in the following sections. + cd caimira + pip install -e . -###### Installing UI: +##### Installing UI: -In order to install the CAiMIRA-native UI version, that links to the previously installed backend, from the root directory of the project, run: +In order to install the CAiMIRA-native UI, that links to the previously installed backend, from the root directory of the project, run: cd cern_caimira pip install -e . -###### Running: +##### Running: -The calculator can be started with the CAiMIRA-native UI using the following command in the project root directory: +The calculator can be started with the CAiMIRA-native UI using the following command (directory independent): python -m cern_caimira.apps.calculator @@ -192,7 +151,7 @@ Each of these commands will start a local version of CAiMIRA, which can be visit ##### Expert-Apps: -The CAiMIRA Expert App and CO~2~ App are legacy tools designed to provide dynamic interaction with the CAiMIRA model parameters. +The CAiMIRA Expert App and CO2 App are legacy tools designed to provide dynamic interaction with the CAiMIRA model parameters. !!! warning @@ -282,6 +241,69 @@ CAiMIRA includes comprehensive documentation, which can be compiled and viewed l The documentation can now be accessed at [http://0.0.0.0:8080/](http://0.0.0.0:8080/). +#### Backend + +The CAiMIRA backend includes the logic underlying the [physics model](https://caimira-test.docs.cern.ch/root/physics_model/) and the REST API for programmatic interaction with the models. Local installation enables full access to these features, supporting development and testing. + +##### Installing + +CAiMIRA's backend logic can be installed with the following two options: + +1. **From [PyPI](https://pypi.org/project/caimira/)**: + + pip install caimira + + For testing new releases, use the PyPI Test instance by running the following command (directory independent): + + pip install --index-url https://test.pypi.org/simple --extra-index-url https://pypi.org/simple caimira + + !!! info + `--extra-index-url` is necessary to resolve dependencies from PyPI. + +2. **From the [GitLab Repository](https://gitlab.cern.ch/caimira/caimira)1**: + + Clone the repository and install it in editable mode for development by running the following commands: + + git clone https://gitlab.cern.ch/caimira/caimira.git + cd caimira + + In the root directory: + + cd caimira + pip install -e . + + !!! note + 1In case you haven't cloned the repository before. + +##### Running and testing with API + +CAiMIRA backend includes a REST API for programmatic interaction with its models. The following steps describe how to run and test the API locally. + +1. **Run the backend API**: + + python -m caimira.api.app + + The Tornado server will be accessible at [http://localhost:8081/](http://localhost:8081/). + +2. **Test the API**: + + Send a `POST` request to `http://localhost:8081/virus_report` with the required inputs in the body. Example request formats can be found in the [Virus Validator Code](https://gitlab.cern.ch/caimira/caimira/blob/master/caimira/src/caimira/calculator/validators/virus/virus_validator.py#L565). + +3. **Example Response**: + A successful response will return data in the following format: + + !!! success + { + "status": "success", + "message": "Results generated successfully", + "report_data": { + ... + }, + ... + } + + For further details please refer to the [REST API documentation page](../code/rest_api.md). + ### Setting up the full environment This section outlines the steps to build and run the full CAiMIRA environment locally using Docker. It provides instructions for creating the necessary Docker images, configuring authentication, and running the application with Docker Compose. From 1c3f0f527898040e735fb4f2b35e921201658474 Mon Sep 17 00:00:00 2001 From: lrdossan Date: Mon, 2 Dec 2024 11:35:01 +0100 Subject: [PATCH 6/8] cleaned sphinx conf file --- caimira/docs/sphinx/conf.py | 3 --- 1 file changed, 3 deletions(-) diff --git a/caimira/docs/sphinx/conf.py b/caimira/docs/sphinx/conf.py index a763660d..e7540e5b 100644 --- a/caimira/docs/sphinx/conf.py +++ b/caimira/docs/sphinx/conf.py @@ -17,11 +17,8 @@ # -- Project information ----------------------------------------------------- project = 'CAiMIRA' -copyright = '2024, Andre Henriques et al.' author = 'Andre Henriques et al.' -release = '1.0.0' - # -- General configuration --------------------------------------------------- extensions = ['sphinx.ext.autodoc', 'sphinx_markdown_builder'] From f4b3b1b571d3633a6fe804cd44a93d6e6802d6e1 Mon Sep 17 00:00:00 2001 From: Andre Henriques Date: Mon, 2 Dec 2024 14:00:00 +0100 Subject: [PATCH 7/8] final update to installation md --- caimira/docs/mkdocs/docs/root/installation.md | 20 +++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/caimira/docs/mkdocs/docs/root/installation.md b/caimira/docs/mkdocs/docs/root/installation.md index 24c93421..98169772 100644 --- a/caimira/docs/mkdocs/docs/root/installation.md +++ b/caimira/docs/mkdocs/docs/root/installation.md @@ -83,18 +83,20 @@ Before proceeding with the development installation of CAiMIRA, ensure that your This section provides instructions for setting up, running, and testing CAiMIRA in a local development environment. -Cloning the full repository from GitLab is required for using the [native Calculator app](#calculator), running [tests](#tests), [profiling](#profiler), or generating [documentation](#docs). This ensures access to both the backend and the native UI, along with all tools and resources. +Cloning the full repository from GitLab is required for using the [native Calculator app](#calculator), running [tests](#tests), [profiling](#profiler), or generating [documentation](#docs). -The repository can be cloned with the following command: +**For development and/or running the backend model alone (without a UI), or for REST API integration, go directly to the [Backend](#backend) section.** - git clone https://gitlab.cern.ch/caimira/caimira.git - cd caimira +The repository can be cloned with the following command: !!! note The directory in which you run these commands will be the root directory of your project. -!!! warning - If only the backend functionality is needed, such as for REST API integration or standalone use, the repository does not necessarily needs to be cloned. Instead, the backend can be installed and run directly using the instructions provided in the [backend](#backend) section. +``` +git clone https://gitlab.cern.ch/caimira/caimira.git +``` + +This ensures access to both the backend and the native UI, along with all tools and resources. #### Calculator @@ -158,9 +160,11 @@ The CAiMIRA Expert App and CO2 App are legacy tools designed to provi The `ExpertApplication` and `CO2Application` are no longer actively maintained but will remain in the codebase for legacy purposes. Please note that the functionality of these applications might be compromised due to deprecation issues. -###### Running the Applications +These apps only work within Jupyter notebooks. -These applications only work within Jupyter notebooks. Attempting to run them outside of a Jupyter environment may result in errors or degraded functionality. +!!! warning + + Attempting to run them outside of a Jupyter environment may result in errors or degraded functionality. 1. **Install dependencies**: From 90fd2a503daa09e7f03fc5074c0d5e4dbba62f5c Mon Sep 17 00:00:00 2001 From: lrdossan Date: Tue, 3 Dec 2024 10:45:57 +0100 Subject: [PATCH 8/8] moved section of test instance of pypi to development section in code > rest api page --- caimira/docs/mkdocs/docs/code/rest_api.md | 17 +++++++++++------ caimira/docs/mkdocs/docs/root/installation.md | 7 ------- 2 files changed, 11 insertions(+), 13 deletions(-) diff --git a/caimira/docs/mkdocs/docs/code/rest_api.md b/caimira/docs/mkdocs/docs/code/rest_api.md index e24425bc..929a9ed0 100644 --- a/caimira/docs/mkdocs/docs/code/rest_api.md +++ b/caimira/docs/mkdocs/docs/code/rest_api.md @@ -54,11 +54,7 @@ To run the API, follow these steps from the root directory of the project: - From [PyPI](https://pypi.org/project/caimira/): - pip install --index-url https://test.pypi.org/simple --extra-index-url https://pypi.org/simple caimira - - !!! info - `--extra-index-url` is necessary to resolve dependencies from PyPI. - + pip install caimira 2. Run the backend: @@ -207,4 +203,13 @@ As the project is growing, more endpoints targeted to specific tasks will be dev "room_capacity": "10", "room_volume": "60", "total_people": "2" - }' \ No newline at end of file + }' + +#### Development + +For testing new releases, use the PyPI Test instance by running the following command (directory independent): + + pip install --index-url https://test.pypi.org/simple --extra-index-url https://pypi.org/simple caimira + +!!! info + `--extra-index-url` is necessary to resolve dependencies from PyPI. diff --git a/caimira/docs/mkdocs/docs/root/installation.md b/caimira/docs/mkdocs/docs/root/installation.md index 98169772..2bdc7ef9 100644 --- a/caimira/docs/mkdocs/docs/root/installation.md +++ b/caimira/docs/mkdocs/docs/root/installation.md @@ -257,13 +257,6 @@ CAiMIRA's backend logic can be installed with the following two options: pip install caimira - For testing new releases, use the PyPI Test instance by running the following command (directory independent): - - pip install --index-url https://test.pypi.org/simple --extra-index-url https://pypi.org/simple caimira - - !!! info - `--extra-index-url` is necessary to resolve dependencies from PyPI. - 2. **From the [GitLab Repository](https://gitlab.cern.ch/caimira/caimira)1**: Clone the repository and install it in editable mode for development by running the following commands: