docs(studies-create): add the topic "How to Create a New Study?"

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

@@ -5,8 +5,12 @@ date: 2023-03-10
 revision: 2024-07-03
 tags:
 
-- upgrade
-- version
+  - tutorial
+  - guide
+  - upgrade
+  - version
+  - study management
+  - raw
 
 ---
 
@@ -63,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/user-guide/1-interface.md

@@ -120,7 +120,7 @@ Example of the detailed view of a matrix node (txt data files):
 ## Data management
 
 The data view display dataset which are list of matrices.
-These matrices can then be used as argument in [variant manager commands](./3-variant_manager.md#base-commands).
+These matrices can then be used as argument in [variant manager commands](./3-variant_manager.md#command-list).
 
 ![](../assets/media/img/userguide_dataset_listing.png)
 

mkdocs.yml

@@ -58,6 +58,7 @@ nav:
               - 'Main Topics': 'user-guide/study/06-table-mode.md'
       - 'Variant manager': 'user-guide/3-variant_manager.md'
   - 'How to':
+      - 'Create a study': 'how-to/studies-create.md'
       - 'Import a study': 'how-to/studies-import.md'
       - 'Upgrade a study': 'how-to/studies-upgrade.md'
   - 'Build':