docs(user-guide): improve the user guide and add "How to Create a New…

… Study?" topic (#2081)

docs/how-to/studies-create.md

@@ -0,0 +1,160 @@
+---
+title: How to Create a New Study?
+author: Laurent LAPORTE <[email protected]>
+date: 2024-07-03
+tags:
+
+  - tutorial
+  - guide
+  - create
+  - version
+  - new
+  - study management
+  - workspace
+---
+
+# How to Create a New Study?
+
+Creating a new study in Antares Web is a straightforward process designed to facilitate users in setting up their energy
+system simulations.
+This guide will walk you through the steps to create a new study, from initial setup to finalization.
+
+## Open the "Create Study" dialog
+
+Navigate to the "Studies" pages to display the list of studies.
+Click on the "Create" button to open the "Create Study" dialog box.
+
+![List of studies](../assets/media/how-to/study-create-button.png)
+
+## Fill in Study Properties
+
+In the "Create Study" dialog, you will be prompted to enter details about your study, such as:
+
+- **Study Name**: Give your study a unique and descriptive name.
+- **Version**: Select the version you wish to use, by default, the latest version is selected.
+- **Permission**:
+    - **Public Mode**: Select this option if you want to share your study with other users (it is recommended to
+      select "READ" permission).
+    - **Group**: Choose the groups you want to share your study with.
+- **Metadata**:
+    - **Tag**: Add tags to your study to help categorize and organize it (enter each tag, and presse Ctrl+Enter to add
+      it).
+
+![Create Study Form](../assets/media/how-to/study-create-form.png)
+
+Validate the form by clicking the "Save" button.
+
+Your study is automatically saved in the `default` folder, which is the default folder of managed studies.
+
+## Customize Study Properties
+
+After creating your study, you can customize it further by moving it in a subfolder, changing its permission, or adding
+metadata.
+
+Select the `default` folder to display the list of studies in this folder.
+Click on the "More options" button of your study to access the "Properties" and "Move" options.
+
+![Other Options Menu](../assets/media/how-to/study-create-other-options.png)
+
+### Move Study in a Subfolder
+
+To move your study in a subfolder, click on the "Move" option.
+The "Move Study" dialog opens, allowing you to select the destination folder.
+
+Enter the name of the subfolder and validate by clicking the "Save" button.
+
+![Move Study Dialog](../assets/media/how-to/study-creation-move-to-subfolder.png)
+
+If the subfolder does not exist, it will be created automatically.
+
+### Edit the Study Properties
+
+To edit the study properties, click on the "Properties" option.
+The "Edit Study" dialog opens, allowing you to modify the study name, permission, and metadata:
+
+- **Study Name**: Give your study a unique and descriptive name.
+- **Permission**:
+    - **Public Mode**: Select this option if you want to share your study with other users (it is recommended to
+      select "READ" permission).
+    - **Group**: Choose the groups you want to share your study with.
+- **Metadata**:
+    - **Tag**: Add tags to your study to help categorize and organize it (enter each tag, and presse Ctrl+Enter to add
+      it).
+
+![Edit Study Dialog](../assets/media/how-to/study-creation-edit-properties.png)
+
+Validate the form by clicking the "Save" button.
+
+> **NOTE:** It is not possible to modify the version of a study after its creation,
+> but you can still upgrade the version of the study.
+> Refer to the [How to Upgrade a Study?](studies-upgrade.md) section for more information.
+
+## Creating a Study Using the API Endpoint
+
+The following Python script demonstrates how to create a study using the API endpoint `POST /v1/studies`:
+
+You need to provide the following parameters:
+
+- `name`: name of the study
+- `version`: version of the study
+- `groups`: list of groups to which the study will be assigned (optional)
+
+Make sure you have the correct API URL and a valid authentication token.
+
+```python
+import httpx  # or requests
+
+URL = "https://antares-web/api"
+TOKEN = "<your authentication token>"
+
+study = {
+    "name": "My New Study",
+    "version": 860,
+    "groups": "group1, group2"
+}
+
+with httpx.Client(verify=False, headers={"Authorization ": f"Bearer {TOKEN}"}) as client:
+    res = client.post(f"{URL}/v1/studies", params=study)
+
+res.raise_for_status()
+study_id = res.json()
+```
+
+The script above creates a new study named `My New Study` with version `860` and assigns it to the groups `group1`
+and `group2`.
+
+Here is a breakdown of what each part of the code does:
+
+1. `import httpx`: This line imports the `httpx` library, which is used for making HTTP requests in Python.
+   Alternatively, the `requests` library can be used instead of `httpx` for the same purpose.
+
+2. `URL = "https://antares-web/api"`: This line sets the URL to which the POST request will be made.
+   You need to provide the right URL according to your own Antares Web server.
+
+3. `TOKEN = "<your authentication token>"`: This line sets the authentication token that will be used in the request.
+   You should replace `<your authentication token>` with your actual authentication token.
+
+4. The `study = {...}` block defines the properties of the study to be created.
+
+5. The `with httpx.Client(verify=False, headers=...) as client:` block creates an HTTP client.
+   The `verify=False` argument is used to disable SSL certificate verification.
+   The `headers={"Authorization ": f"Bearer {TOKEN}"}` argument sets authentication token.
+
+6. The `res = client.post(f"{URL}/v1/studies", params=study)` line sends a POST request to create the study.
+   The `params=study` argument sends the study properties as JSON data in the request body.
+
+7. `res.raise_for_status()` checks if the response from the server indicates an error.
+   If an error is detected, it raises an exception.
+
+8. `study_id = res.json()` parses the response from the server, assuming it is in JSON format,
+   and assigns it to the variable `study_id`.
+
+See also:
+
+- ["User account & api tokens"](../user-guide/1-interface.md#user-account-and-api-tokens) in the user guide.
+
+## See also
+
+- [How to Upgrade a Study?](studies-upgrade.md) -- Upgrade a study to a recent version
+- [How to Import a Compressed Study?](studies-import.md) - Import a study from a compressed file
+- How to Run a study simulation? - Run a simulation on a study

docs/how-to/studies-import.md

@@ -4,9 +4,14 @@ author: Laurent LAPORTE <[email protected]>
 date: 2023-10-25
 tags:
 
-  - import
-  - zip
-  - 7z
+   - tutorial
+   - guide
+   - import
+   - zip
+   - 7z
+   - compressed
+   - study management
+   - workspace
 
 ---
 
@@ -56,10 +61,20 @@ The import dialog box will appear. Click the "Browse" button to select the compr
 
 You can also drag and drop the compressed file into the dialog box.
 
-Once imported, you can see the study in the list of studies. Select the "default" workspace to view the imported study. You can also search for the study by name using the search input.
+Once imported, you can see the study in the list of studies. Select the "default" workspace to view the imported study.
+You can also search for the study by name using the search input.
 
 ![studies-import-studies-list.png](../assets/media/how-to/studies-import-studies-list.png)
 
+> **NOTE:** The properties of the imported study can be modified by clicking on the "More options" button and
+> selecting "Properties". You can change the study name, permission, and metadata.
+> Refer to the [Customize Study Properties](studies-create.md#customize-study-properties) paragraph
+> for more information.
+
+> **NOTE:** It is not possible to modify the version of a study after its import,
+> but you can still upgrade the version of the study.
+> Refer to the [How to Upgrade a Study?](studies-upgrade.md) section for more information.
+
 ## Importing a Study Using the API Endpoint
 
 The following Python script demonstrates how to import a study using the API endpoint `POST /v1/studies/_import`:
@@ -78,21 +93,20 @@ URL = "https://antares-web/api"
 TOKEN = "<your authentication token>"
 
 with open("perso/new_study.zip", mode="rb") as fd:
-    with httpx.Client(verify=False) as client:
+    with httpx.Client(verify=False, headers={"Authorization ": f"Bearer {TOKEN}"}) as client:
         res = client.post(
             f"{URL}/v1/studies/_import",
-            headers={"Authorization": f"Bearer {TOKEN}"},
             files={"study": fd},
             params={"groups": "foo,bar"},
         )
 
 res.raise_for_status()
-study_uuid = res.json()
+study_id = res.json()
 ```
 
 The script above imports the compressed file `perso/new_study.zip` and assigns the study to the groups `foo` and `bar`.
 
-Here's a breakdown of what each part of the code does:
+Here is a breakdown of what each part of the code does:
 
 1. `import httpx`: This line imports the `httpx` library, which is used for making HTTP requests in Python.
    Alternatively, the `requests` library can be used instead of `httpx` for the same purpose.
@@ -105,19 +119,26 @@ Here's a breakdown of what each part of the code does:
 
 4. The `with open("perso/new_study.zip", mode="rb") as fd:` block opens the specified compressed file in binary mode.
 
-5. The `with httpx.Client(verify=False) as client:` block creates an HTTP client. 
+5. The `with httpx.Client(verify=False, headers=...) as client:` block creates an HTTP client.
    The `verify=False` argument is used to disable SSL certificate verification.
+   The `headers={"Authorization ": f"Bearer {TOKEN}"}` argument sets authentication token.
 
 6. `res = client.post(...)` makes a POST request to the specified URL with the provided parameters.
    It sends the file contents, sets the headers with the authentication token, and adds query parameters.
 
 7. `res.raise_for_status()` checks if the response from the server indicates an error.
    If an error is detected, it raises an exception.
-   You may have the HTTP error 415  if the file is not a valid ZIP of 7z file.
+   You may have the HTTP error 415 if the file is not a valid ZIP of 7z file.
 
-8. `study_uuid = res.json()` parses the response from the server, assuming it is in JSON format,
-   and assigns it to the variable `study_uuid`.
+8. `study_id = res.json()` parses the response from the server, assuming it is in JSON format,
+   and assigns it to the variable `study_id`.
 
 See also:
 
 - ["User account & api tokens"](../user-guide/1-interface.md#user-account-and-api-tokens) in the user guide.
+
+## See also
+
+- [How to Create a New Study?](studies-create.md) -- Create a new study in Antares Web
+- [How to Upgrade a Study?](studies-upgrade.md) -- Upgrade a study to a recent version
+- How to Run a study simulation? - Run a simulation on a study

docs/how-to/studies-upgrade.md

@@ -2,10 +2,15 @@
 title: How to Upgrade a Study?
 author: Laurent LAPORTE <[email protected]>
 date: 2023-03-10
+revision: 2024-07-03
 tags:
 
-- upgrade
-- version
+  - tutorial
+  - guide
+  - upgrade
+  - version
+  - study management
+  - raw
 
 ---
 
@@ -31,6 +36,10 @@ hesitate to contact our support team for assistance.
 
 ## Upgrading
 
+> **WARNING:** Upgrading a study is only possible if the study is a **raw study** without any variants,
+> as it is not possible to update its descendants. Also, upgrading a variant study is not possible.
+> If you have a variant study, you must first create a new raw study and then upgrade it.
+
 To upgrade your study to the latest version of Antares Web and Antares Simulator, you can follow these steps:
 
 On the main page of the study, you can find the version number at the top of the menu bar:
@@ -58,5 +67,6 @@ Once the upgrade is complete, you can open your study and perform the manual upg
 
 ## See also
 
-- Create a new study in the latest version
-- Run a study in the latest version 
+- [How to Create a New Study?](studies-create.md) -- Create a new study in Antares Web
+- [How to Import a Compressed Study?](studies-import.md) - Import a study from a compressed file
+- How to Run a study simulation? - Run a simulation on a study

docs/index.md

@@ -4,48 +4,57 @@
 ![TypeScript](https://img.shields.io/badge/TypeScript-00599c?style=for-the-badge&logo=TypeScript&logoColor=61DAFB)
 ![React](https://img.shields.io/badge/React-00599c?style=for-the-badge&logo=react&logoColor=61DAFB)
 
+![](assets/antares.png "Antares Web Logo")
+> Web API and UI for [Antares Simulator][antares-simulator-website]
 
-![antares logo](assets/antares.png)
-> Web API and UI for [Antares Simulator][antareswebsite]
-
-This package works along with RTE's adequacy software [Antares Simulator][antareswebsite] that is also [hosted on github][antares-github]
-
-Please see the [Antares Web Documentation][readthedocs] for an introductory tutorial,
-and a full user guide. Visit the [Antares-Simulator Documentation][readthedocs-antares] for more insights on ANTARES. 
+Please see the [Antares Web Documentation][antares-web-readthedocs] for an introductory tutorial,
+and a full user guide. Visit the [Antares-Simulator Documentation][antares-simulator-readthedocs] for more insights on
+ANTARES.
 
 ## Introduction
 
-`antares-web` is a server api interfacing Antares Simulator solver and studies management. It provides a web application to manage studies
-adding more features to simple edition.
+Welcome to `antares-web`, a comprehensive web application designed to interface with RTE’s adequacy software,
+the [Antares Simulator][antares-simulator-website], also [hosted on GitHub][antares-simulator-github].
+The Antares Simulator is an open-source power system simulator for anyone valuing the quantification of adequacy or the
+economic performance of interconnected energy systems over short or distant time horizons.
+It enables detailed modeling of energy consumption, generation, and transportation, performing probabilistic simulations
+across numerous year-long scenarios, each consisting of 8760 hourly time-frames.
+
+`antares-web` serves as a server API interfacing with Antares Simulator studies, providing a web application to manage
+studies while adding features for enhanced edition capabilities.
 
-This brings:
+This integration brings:
 
-> - **application interoperability** : assign unique id to studies, expose operation endpoint api
->
-> - **optimized storage**: extract matrices data and share them between studies, archive mode
->
-> - **variant management**: add a new editing description language and generation tool
->
-> - **user accounts** : add user management and permission system
+- **Application Interoperability**: Assign unique IDs to studies and expose operations through an endpoint API,
+  facilitating integration with other applications and services.
+- **Optimized Storage**: Extract matrices data and share them between studies, supporting archive mode.
+- **Variant Management**: Introduce a new editing description language and generation tool.
+- **User Accounts**: Implement user management and permission systems.
 
 ## Documentation
 
 - [Building the application](./install/0-INSTALL.md)
 - [Using the application](./user-guide/0-introduction.md)
 - [Contributing to the application code](./architecture/0-introduction.md)
 
-
 `Antares-Web` is currently under development. Feel free to submit any issue.
 
+[ci_result]: https://github.com/AntaresSimulatorTeam/AntaREST/actions/workflows/main.yml/badge.svg
+
+[ci_result_link]: https://github.com/AntaresSimulatorTeam/AntaREST/actions/workflows/main.yml
 
-[ci_result]: https://github.com/AntaresSimulatorTeam/AntaREST/workflows/main/badge.svg
-[ci_result_link]: https://github.com/AntaresSimulatorTeam/AntaREST/actions?query=workflow%3Amain
 [coverage_result]: https://sonarcloud.io/api/project_badges/measure?project=AntaresSimulatorTeam_api-iso-antares&metric=coverage
+
 [coverage_result_link]: https://sonarcloud.io/dashboard?id=AntaresSimulatorTeam_api-iso-antares
+
 [license_badge]: https://img.shields.io/github/license/AntaresSimulatorTeam/AntaREST
+
 [license_link]: https://www.apache.org/licenses/LICENSE-2.0
 
-[antares-github]: https://github.com/AntaresSimulatorTeam/Antares_Simulator
-[readthedocs]: https://antares-web.readthedocs.io/
-[readthedocs-antares]: https://antares-simulator.readthedocs.io/
-[antareswebsite]: https://antares-simulator.org
+[antares-web-readthedocs]: https://antares-web.readthedocs.io/
+
+[antares-simulator-readthedocs]: https://antares-simulator.readthedocs.io/
+
+[antares-simulator-website]: https://antares-simulator.org
+
+[antares-simulator-github]: https://github.com/AntaresSimulatorTeam/Antares_Simulator