docs: correct and improve the "Variant Manager" documentation (#1637)

LICENSE

@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright [2021] [RTE]
+   Copyright © 2007 - 2023 RTE
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

antarest/study/storage/variantstudy/business/utils.py

@@ -1,7 +1,8 @@
-from typing import Union, List, Any, Sequence, Optional
+from typing import Any, Dict, List, Optional, Sequence, Union
 
 from antarest.core.model import JSON
 from antarest.matrixstore.model import MatrixData
+from antarest.matrixstore.service import ISimpleMatrixService
 from antarest.study.storage.rawstudy.model.filesystem.factory import FileStudy
 from antarest.study.storage.variantstudy.business.matrix_constants_generator import (
     MATRIX_PROTOCOL_PREFIX,
@@ -11,24 +12,39 @@
 
 
 def validate_matrix(
-    matrix: Union[List[List[MatrixData]], str], values: Any
+    matrix: Union[List[List[MatrixData]], str], values: Dict[str, Any]
 ) -> str:
-    matrix_id: str
+    """
+    Validates the matrix, stores the matrix array in the matrices repository,
+    and returns a reference to the stored array.
+
+    Args:
+        matrix: The matrix data or matrix link to validate.
+        values: Additional values used during the validation process.
+            It should contain the following key-value pairs:
+            - "command_context": An object providing access to matrix services.
+              It should have a "matrix_service" attribute which allows creating
+              and checking the existence of matrices.
+
+    Returns:
+        The ID of the validated matrix prefixed by "matrix://".
+
+    Raises:
+        TypeError: If the provided matrix is neither a matrix nor a link to a matrix.
+        ValueError: If the matrix ID does not exist.
+    """
+    # fmt: off
+    matrix_service: ISimpleMatrixService = values["command_context"].matrix_service
     if isinstance(matrix, list):
-        matrix_id = MATRIX_PROTOCOL_PREFIX + values[
-            "command_context"
-        ].matrix_service.create(data=matrix)
+        return MATRIX_PROTOCOL_PREFIX + matrix_service.create(data=matrix)
     elif isinstance(matrix, str):
-        if values["command_context"].matrix_service.exists(matrix):
-            matrix_id = MATRIX_PROTOCOL_PREFIX + matrix
+        if matrix_service.exists(matrix):
+            return MATRIX_PROTOCOL_PREFIX + matrix
         else:
             raise ValueError(f"Matrix with id {matrix} does not exist")
     else:
-        raise ValueError(
-            f"The data {matrix} is neither a matrix nor a link to a matrix"
-        )
-
-    return matrix_id
+        raise TypeError(f"The data {matrix} is neither a matrix nor a link to a matrix")
+    # fmt: on
 
 
 def get_or_create_section(json_ini: JSON, section: str) -> JSON:

antarest/study/storage/variantstudy/model/command/icommand.py

@@ -33,21 +33,57 @@ class ICommand(ABC, BaseModel):
     version: int
     command_context: CommandContext
 
-    @abstractmethod
-    def _apply(self, study_data: FileStudy) -> CommandOutput:
-        raise NotImplementedError()
-
     @abstractmethod
     def _apply_config(
         self, study_data: FileStudyTreeConfig
     ) -> Tuple[CommandOutput, Dict[str, Any]]:
+        """
+        Applies configuration changes to the study data.
+
+        Args:
+            study_data: The study data configuration.
+
+        Returns:
+            A tuple containing the command output and a dictionary of extra data.
+        """
         raise NotImplementedError()
 
     def apply_config(self, study_data: FileStudyTreeConfig) -> CommandOutput:
+        """
+        Applies configuration changes to the study data.
+
+        Args:
+            study_data: The study data configuration.
+
+        Returns:
+            The command output.
+        """
         output, _ = self._apply_config(study_data)
         return output
 
+    @abstractmethod
+    def _apply(self, study_data: FileStudy) -> CommandOutput:
+        """
+        Applies the study data to update storage configurations and saves the changes.
+
+        Args:
+            study_data: The study data to be applied.
+
+        Returns:
+            The output of the command execution.
+        """
+        raise NotImplementedError()
+
     def apply(self, study_data: FileStudy) -> CommandOutput:
+        """
+        Applies the study data to update storage configurations and saves the changes.
+
+        Args:
+            study_data: The study data to be applied.
+
+        Returns:
+            The output of the command execution.
+        """
         try:
             return self._apply(study_data)
         except Exception as e:
@@ -65,10 +101,18 @@ def apply(self, study_data: FileStudy) -> CommandOutput:
 
     @abstractmethod
     def to_dto(self) -> CommandDTO:
+        """
+        Converts the current object to a Data Transfer Object (DTO)
+        which is stored in the `CommandBlock` in the database.
+
+        Returns:
+            The DTO object representing the current command.
+        """
         raise NotImplementedError()
 
     @abstractmethod
     def match_signature(self) -> str:
+        """Returns the command signature."""
         raise NotImplementedError()
 
     @abstractmethod
@@ -84,19 +128,50 @@ def match(self, other: "ICommand", equal: bool = False) -> bool:
         """
         raise NotImplementedError()
 
-    def create_diff(self, other: "ICommand") -> List["ICommand"]:
-        assert_this(self.match(other))
-        return self._create_diff(other)
-
     @abstractmethod
     def _create_diff(self, other: "ICommand") -> List["ICommand"]:
+        """
+        Creates a list of commands representing the differences between
+        the current instance and another `ICommand` object.
+
+        Args:
+            other: Another ICommand object to compare against.
+
+        Returns:
+            A list of commands representing the differences between
+            the two `ICommand` objects.
+        """
         raise NotImplementedError()
 
+    def create_diff(self, other: "ICommand") -> List["ICommand"]:
+        """
+        Creates a list of commands representing the differences between
+        the current instance and another `ICommand` object.
+
+        Args:
+            other: Another ICommand object to compare against.
+
+        Returns:
+            A list of commands representing the differences between
+            the two `ICommand` objects.
+        """
+        assert_this(self.match(other))
+        return self._create_diff(other)
+
     @abstractmethod
     def get_inner_matrices(self) -> List[str]:
+        """
+        Retrieves the list of matrix IDs.
+        """
         raise NotImplementedError()
 
     def get_command_extractor(self) -> "CommandExtractor":
+        """
+        Create a new `CommandExtractor` used to revert the command changes.
+
+        Returns:
+            An instance of `CommandExtractor`.
+        """
         from antarest.study.storage.variantstudy.business.command_extractor import (
             CommandExtractor,
         )