From fa3f5407ef740977fd1015fe3a3c05abbea34c79 Mon Sep 17 00:00:00 2001 From: Laurent LAPORTE Date: Wed, 3 Jul 2024 12:04:12 +0200 Subject: [PATCH] docs: improve the User Guide documentation --- docs/index.md | 57 ++++++++++++++++------------ docs/user-guide/0-introduction.md | 42 +++++++++++--------- docs/user-guide/1-interface.md | 49 ++++++++++++++---------- docs/user-guide/3-variant_manager.md | 2 +- 4 files changed, 87 insertions(+), 63 deletions(-) diff --git a/docs/index.md b/docs/index.md index de7365f71b..4e1a2f818f 100644 --- a/docs/index.md +++ b/docs/index.md @@ -4,29 +4,32 @@ ![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 @@ -34,18 +37,24 @@ This brings: - [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 diff --git a/docs/user-guide/0-introduction.md b/docs/user-guide/0-introduction.md index 99fa5637ac..a57bbab9d0 100644 --- a/docs/user-guide/0-introduction.md +++ b/docs/user-guide/0-introduction.md @@ -1,26 +1,34 @@ # Introduction -![](../assets/antares.png) +![](../assets/antares.png "Antares Web Logo") -This package works along with RTE's adequacy software [Antares Simulator](https://antares-simulator.org) -that is also [hosted on github][antares-github] +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` is a server api interfacing Antares Simulator studies. It provides a web application to manage studies -adding more features to simple edition. +`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. -## Variant manager +## Variant Manager -`antares-web` brings an edition event store that provides a way to edit a study while keeping track of changes. -It eases the creation of "variants" of a study and allow an explicit diff change between studies. +`antares-web` introduces an edition event store that tracks changes, simplifying the creation of study "variants" and +allowing for explicit diff change comparisons between studies. -You can read more information in [using the variant manager here](./3-variant_manager.md) +Explore the suite of features `antares-web` offers to enhance the Antares Simulator, improving study management, +interoperability, and user collaboration. + + +[antares-simulator-website]: https://antares-simulator.org + +[antares-simulator-github]: https://github.com/AntaresSimulatorTeam/Antares_Simulator diff --git a/docs/user-guide/1-interface.md b/docs/user-guide/1-interface.md index ca002c205d..8f6834d453 100644 --- a/docs/user-guide/1-interface.md +++ b/docs/user-guide/1-interface.md @@ -6,39 +6,43 @@ - [Strict folder filtering](#strict-folder-filtering) - [Zipped output retrieval](#launch-dialog) +The application is split into 3 main menus: Studies, Jobs, and Data. +API documentation, external reference links, and user account details are also available. -The application is split in 3 main menus : Studies, Jobs and Data. -API documentation, external reference links and user account details is also available. - - - "Studies" is the main section and redirects to the study listing where we can browse studies and work -on them. - - "Jobs" is a monitoring section which display currently running or latest execution jobs - - "Data" is a section where we can manage matrix data that can be then used in the [variant manager](#variant-management) +- "Studies" is the main section and redirects to the study listing where we can browse studies and work on them. +- "Jobs" is a monitoring section that displays currently running or latest execution jobs. +- "Data" is a section where we can manage matrix data that can then be used in + the [variant manager](#variant-management). ![](../assets/media/img/userguide_mainmenu.png) ## Study listing The study listing view is the main view, which provides : + - the listing of existing studies - filters/sorting/tree view - creation/import tool Studies are linked to a "workspace" which refers to a storage disk. The workspace "default" (orange colored) is -the internal storage where "managed" studies live. These studies files aren't meant to be accessible directly (via disk mount for instance). -The other workspaces are studies that are found on mounted workspace and their unique ID can change if the studies are moved. +the internal storage where "managed" studies live. These studies files aren't meant to be accessible directly (via disk +mount for instance). +The other workspaces are studies that are found on mounted workspace and their unique ID can change if the studies are +moved. + +Copied studies are always copied within the managed workspace. These managed studies though not directly accessible +offers additional features: -Copied studies are always copied within the managed workspace. These managed studies though not directly accessible offers additional features: - a permanent ID - archiving - variant creation - faster operations - storage improvements - ![](../assets/media/img/userguide_studylisting.png) Some actions are available from this view: + - launching the study simulation - exporting the study - deleting the study @@ -49,13 +53,12 @@ Some actions are available from this view: When launching a study, a dialog will open with some choices. - ![](../assets/media/img/userguide_launch_dialog.png) - ### Launch batch mode -To launch multiple studies at once, we can click on the checkbox icon to enable selection mode. In this mode, we can click +To launch multiple studies at once, we can click on the checkbox icon to enable selection mode. In this mode, we can +click on study cards to select / unselect them. Then clicking on the launch button will open the launch dialog. @@ -63,17 +66,18 @@ the launch dialog. ### Strict folder filtering -The folder icon next to the breadcrumb path allow to filter (when activated) the studies to only the direct descendant of the selected folder. +The folder icon next to the breadcrumb path allow to filter (when activated) the studies to only the direct descendant +of the selected folder. ![](../assets/media/img/userguide_strict_folder_filter.png) - For more operation over a study, we can click on a study "explore" button and go to the dedicated study view. The url of dedicated study view can be bookmarked for sharing or quick access. ## Study view The study view is composed of 2 or 3 main menus depending on the managed status of the study. + - ["Information"](#overview) view is an overview of the study - ["Detailed view"](#detailed-view) is a raw view of the study contents - ["Variant"](#variant-management) view is where we can manage the variant of a study if it is managed @@ -81,6 +85,7 @@ The study view is composed of 2 or 3 main menus depending on the managed status ### Overview The overview provides access to : + - basic metadata - name and permission edition (a study can be public or associated with groups with specific permissions) - simulation execution monitoring @@ -92,6 +97,7 @@ The overview provides access to : The variant command tab is only available for managed variant studies. It shows an edition view where we can: + - edit the command list composing the variant - monitor or verify the result of the generation process @@ -99,11 +105,10 @@ It shows an edition view where we can: ### Detailed view -The detailed view is a tree representation of a study files. +The detailed view is a tree representation of a study files. It can be browsed and node can be viewed and edited. :warning: The view can take some time to load the first time. - Example of the detailed view of a configuration node (ini files): ![](../assets/media/img/userguide_treeview_json.png) @@ -112,7 +117,6 @@ Example of the detailed view of a matrix node (txt data files): ![](../assets/media/img/userguide_treeview_matrix.png) - ## Data management The data view display dataset which are list of matrices. @@ -131,12 +135,15 @@ These token can be used in scripts that will use the [API](#api-documentation). ![](../assets/media/img/userguide_token_listing.png) -We can choose to assign specific permission to the token and can choose if the scripts using the token will impersonate our user or not. +We can choose to assign specific permission to the token and can choose if the scripts using the token will impersonate +our user or not. If we choose the later, studies created using the token will be owned by a new user that will have the token's name. ![](../assets/media/img/userguide_token_creation.png) -We have to save the token (as it is generated once and not saved). It will then be used as an authentication token in HTTP Basic Auth, eg.: +We have to save the token (as it is generated once and not saved). It will then be used as an authentication token in +HTTP Basic Auth, eg.: + ``` curl -H 'Authorization: Bearer ' https://antares-web/api/studies ``` diff --git a/docs/user-guide/3-variant_manager.md b/docs/user-guide/3-variant_manager.md index 6762ee4c86..ac310cddad 100644 --- a/docs/user-guide/3-variant_manager.md +++ b/docs/user-guide/3-variant_manager.md @@ -356,7 +356,7 @@ Coming soon ### Composite commands -Comming soon +Coming soon ## CLI Tool