Improve ref man

taipy/config/__init__.py

@@ -9,12 +9,41 @@
 # an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
 # specific language governing permissions and limitations under the License.
 
-"""# Taipy Config
+"""# Taipy Config package
 
-The Taipy Config package is a Python library designed to configure a Taipy application.
+The `taipy.config` package provides features to configure a Taipy application.
 
-The main entrypoint is the `Config^` singleton class. It exposes some methods to configure the
-Taipy application and some attributes to retrieve the configuration values.
+Its main class is the `Config^` singleton. It exposes various static methods
+and attributes to configure the Taipy application and retrieve the configuration values.
+
+!!! example "Standard usage"
+
+    ```python
+    from taipy.config import Config
+    from taipy.config import Frequency
+    from taipy.config import Scope
+
+    data_node_cfg = Config.configure_data_node("my_data_node", scope=Scope.SCENARIO)
+    Config.configure_scenario("my_scenario", additional_data_node_configs=[data_node_cfg], frequency=Frequency.DAILY)
+    Config.configure_core(repository_type="filesystem", storage_folder="my/storage/folder")
+    Config.configure_authentication(protocol="taipy",roles={"user1": ["role1", "TAIPY_READER"]})
+
+    print(Config.data_nodes["my_data_node"].scope)  # Output: SCENARIO
+    print(len(Config.scenarios["my_scenario"].data_nodes))  # Output: 1
+    ```
+
+    In this example, the static methods of the `Config^` singleton are used to configure
+    a Taipy application. The application has one data node configuration and one scenario
+    configuration.
+    We also configure the application to use a filesystem repository and set up authentication.
+
+!!! note "`Frequency^` and `Scope^` for scenario and data nodes configurations"
+
+    Besides the `Config^` class which is the main entrypoint, the `taipy.config` package exposes
+    the `Frequency^` and `Scope^` enums that are frequently used to configure data nodes and
+    scenarios.
+
+    The three objects are exposed in the `taipy^` package directly for convenience.
 
 """
 

taipy/config/checker/issue.py

@@ -15,8 +15,11 @@
 
 @dataclass
 class Issue:
-    """
-    An issue detected in the configuration.
+    """An issue detected in the configuration.
+
+    `Issue` is a dataclass that represents an issue detected during the configuration check
+    process. It contains the necessary information to understand the issue and help the user to fix
+    it.
 
     Attributes:
         level (str): Level of the issue among ERROR, WARNING, INFO.

taipy/config/checker/issue_collector.py

@@ -15,8 +15,13 @@
 
 
 class IssueCollector:
-    """
-    A collection of issues (instances of class `Issue^`).
+    """A collection of configuration issues (instances of class `Issue^`).
+
+    `IssueCollector` is a generic class that collects issues detected during the validation
+    process. In particular, an `IssueCollector` is created and returned by the `Config.check()^`
+    method. It contains all the collected issues separated by severity (ERROR, WARNING, INFO).
+    Each issue is an instance of the class `Issue^` and contains the necessary information to
+    understand the issue and help the user to fix it.
 
     Attributes:
         errors (List[Issue^]): List of ERROR issues collected.

taipy/config/config.py

@@ -27,7 +27,91 @@
 
 
 class Config:
-    """Configuration singleton."""
+    """Singleton class that manages the configuration of a Taipy application.
+
+    The `Config` singleton is the main class to use for configuring a Taipy application.
+    In particular, this class provides:
+
+    1. Various methods to configure the application's behavior
+
+        The Config class provides various methods to configure the application. Each method adds
+        a specific section to the configuration and returns it.
+
+        Here is a non-exhaustive list of configuration method examples:
+
+        - `configure_data_node()^`: Configure a data node adding and returning a `DataNodeConfig^`.
+        - `configure_task()^`: Configure a task adding and returning a `TaskConfig^`.
+        - `configure_scenario()^`: Configure a scenario adding and returning a `ScenarioConfig^`.
+        - `load()^`: Load a TOML configuration file. (This overrides the Python configuration)
+        - more...
+
+        !!! example "Most frequently used configuration methods"
+
+            ```python
+            from taipy import Config
+
+            def by_two(x: int):
+                return x * 2
+
+            input_cfg = Config.configure_data_node("my_input")
+            result_cfg = Config.configure_data_node("my_result")
+            task_cfg = Config.configure_task("my_double", function=by_two, input=input_cfg, output=result_cfg)
+            scenario_cfg = Config.configure_scenario("my_scenario", task_configs=[task_cfg])
+
+            Config.load("config.toml") # Load a configuration file
+            ```
+
+        !!! example "Advanced use case"
+
+            The configuration can be done in three ways: Python code, configuration files, or
+            environment variables. All configuration manners are ultimately merged (overriding the previous way
+            way) to create a final applied configuration. Please refer to the
+            [advanced configuration](../../userman/advanced_features/configuration/advanced-config.md)
+            section from the user manual for more details.
+
+    2. Attributes and methods to retrieve the configuration values.
+
+        Once the configuration is done, you can retrieve the configuration values using the exposed
+        attributes.
+
+        !!! Example "Retrieve configuration values"
+
+            ```python
+            from taipy import Config
+
+            global_cfg = Config.global_config  # Retrieve the global application configuration
+            data_node_cfgs = Config.data_nodes  # Retrieve all data node configurations
+            scenario_cfgs = Config.scenarios  # Retrieve all scenario configurations
+        ```
+
+    3. A few methods to manage the configuration:
+
+        The Config class also provides a few methods to manage the configuration. For example,
+        you can:
+
+        - *Check the configuration for issues*: Use the `Config.check()^` method to check the
+            configuration. It returns an `IssueCollector^` containing all the `Issue^`s
+            found representing the issues with their severity.
+        - *Block the configuration update*: Use the `Config.block_update()^` method to forbid
+            any update on the configuration. This can be useful when you want to ensure that
+            the configuration is not modified at run time. Note that running the `Orchestrator^`
+            service` automatically blocks the configuration update.
+        - *Unblock the configuration update*: Use the `Config.unblock_update()^` method to allow
+            again the update on the configuration.
+        - *Backup the configuration*: Use the `Config.backup()^` method to back up as a TOML
+            file the applied configuration. The applied configuration backed up is the result
+            of the compilation of the three possible configuration methods that overrides each
+            others.
+        - *Restore the configuration*: Use the `Config.restore()^` method to restore a TOML
+            configuration file and replace the current applied configuration.
+        - *Export the configuration*: Use the `Config.export()^` method to export as a TOML file
+            the Python code configuration.
+        - *Load the configuration*: Use the `Config.load()^` method to load a TOML configuration
+            file and replace the current Python configuration.
+        - *Override the configuration*: Use the `Config.override()^` method to load a TOML
+            configuration file and override the current Python configuration.
+
+    """
 
     _ENVIRONMENT_VARIABLE_NAME_WITH_CONFIG_PATH = "TAIPY_CONFIG_PATH"
     __logger = _TaipyLogger._get_logger()

taipy/config/config.pyi

@@ -26,7 +26,91 @@ from .section import Section
 from .unique_section import UniqueSection
 
 class Config:
-    """Configuration singleton."""
+    """Singleton class that manages the configuration of a Taipy application.
+
+    The `Config` singleton is the main class to use for configuring a Taipy application.
+    In particular, this class provides:
+
+    1. Various methods to configure the application's behavior
+
+        The Config class provides various methods to configure the application. Each method adds
+        a specific section to the configuration and returns it.
+
+        Here is a non-exhaustive list of configuration method examples:
+
+        - `configure_data_node()^`: Configure a data node adding and returning a `DataNodeConfig^`.
+        - `configure_task()^`: Configure a task adding and returning a `TaskConfig^`.
+        - `configure_scenario()^`: Configure a scenario adding and returning a `ScenarioConfig^`.
+        - `load()^`: Load a TOML configuration file. (This overrides the Python configuration)
+        - more...
+
+        !!! example "Most frequently used configuration methods"
+
+            ```python
+            from taipy import Config
+
+            def by_two(x: int):
+                return x * 2
+
+            input_cfg = Config.configure_data_node("my_input")
+            result_cfg = Config.configure_data_node("my_result")
+            task_cfg = Config.configure_task("my_double", function=by_two, input=input_cfg, output=result_cfg)
+            scenario_cfg = Config.configure_scenario("my_scenario", task_configs=[task_cfg])
+
+            Config.load("config.toml") # Load a configuration file
+            ```
+
+        !!! example "Advanced use case"
+
+            The configuration can be done in three ways: Python code, configuration files, or
+            environment variables. All configuration manners are ultimately merged (overriding the previous way
+            way) to create a final applied configuration. Please refer to the
+            [advanced configuration](../../userman/advanced_features/configuration/advanced-config.md)
+            section from the user manual for more details.
+
+    2. Attributes and methods to retrieve the configuration values.
+
+        Once the configuration is done, you can retrieve the configuration values using the exposed
+        attributes.
+
+        !!! Example "Retrieve configuration values"
+
+            ```python
+            from taipy import Config
+
+            global_cfg = Config.global_config  # Retrieve the global application configuration
+            data_node_cfgs = Config.data_nodes  # Retrieve all data node configurations
+            scenario_cfgs = Config.scenarios  # Retrieve all scenario configurations
+        ```
+
+    3. A few methods to manage the configuration:
+
+        The Config class also provides a few methods to manage the configuration. For example,
+        you can:
+
+        - *Check the configuration for issues*: Use the `Config.check()^` method to check the
+            configuration. It returns an `IssueCollector^` containing all the `Issue^`s
+            found representing the issues with their severity.
+        - *Block the configuration update*: Use the `Config.block_update()^` method to forbid
+            any update on the configuration. This can be useful when you want to ensure that
+            the configuration is not modified at run time. Note that running the `Orchestrator^`
+            service` automatically blocks the configuration update.
+        - *Unblock the configuration update*: Use the `Config.unblock_update()^` method to allow
+            again the update on the configuration.
+        - *Backup the configuration*: Use the `Config.backup()^` method to back up as a TOML
+            file the applied configuration. The applied configuration backed up is the result
+            of the compilation of the three possible configuration methods that overrides each
+            others.
+        - *Restore the configuration*: Use the `Config.restore()^` method to restore a TOML
+            configuration file and replace the current applied configuration.
+        - *Export the configuration*: Use the `Config.export()^` method to export as a TOML file
+            the Python code configuration.
+        - *Load the configuration*: Use the `Config.load()^` method to load a TOML configuration
+            file and replace the current Python configuration.
+        - *Override the configuration*: Use the `Config.override()^` method to load a TOML
+            configuration file and override the current Python configuration.
+
+    """
     @_Classproperty
     def unique_sections(cls) -> Dict[str, UniqueSection]:
         """Return all unique sections."""

taipy/config/exceptions/__init__.py

@@ -9,13 +9,5 @@
 # an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
 # specific language governing permissions and limitations under the License.
 
-# Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
-# the License. You may obtain a copy of the License at
-#
-#        http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
-# an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
-# specific language governing permissions and limitations under the License.
-
+"""# Exceptions raised by the `taipy.config^` package."""
 from .exceptions import *

taipy/config/global_app/global_app_config.py

@@ -18,8 +18,7 @@
 
 
 class GlobalAppConfig:
-    """
-    Configuration fields related to the global application.
+    """Configuration attributes related to the global application.
 
     Attributes:
         **properties (Dict[str, Any]): A dictionary of additional properties.

taipy/config/section.py

@@ -18,9 +18,30 @@
 
 
 class Section:
-    """A Section as a consistent part of the Config.
+    """An abstract class representing a subdivision of the configuration class `Config^`.
+
+    The role of the subclasses of this class is to define semantically consistent sets of settings
+    related to a particular aspect of the application.
+
+    Here are the various sections in Taipy:
+
+    - `DataNodeConfig^` for configuring data nodes.
+    - `TaskConfig^` for configuring tasks.
+    - `ScenarioConfig^` for configuring scenarios.
+    - `MigrationConfig^` for configuring data migration within the Taipy version management.
+
+    Each Section implementation is defined by a section name (related to the objects they
+    configure), a unique identifier, and a set of properties.
+
+    Some of the Section implementations are designed to be unique, meaning only one instance
+    can exist. They are subclasses of the `UniqueSection^` abstract class such as:
+
+    - `GlobalAppConfig^` for configuring global application settings.
+    - `GuiConfig` for configuring the GUI service.
+    - `CoreSection^` for configuring the core package behavior.
+    - `JobConfig^` for configuring the job orchestration.
+    - `AuthenticationConfig^` for configuring authentication settings.
 
-    A section is defined by the section name (representing the type of objects that are configured) and a section id.
     """
 
     _DEFAULT_KEY = "default"

taipy/config/unique_section.py

@@ -15,9 +15,21 @@
 
 
 class UniqueSection(Section, ABC):
-    """A UniqueSection is a configuration `Section^` that can have only one instance.
+    """An abstract class representing a subdivision of the configuration class `Config^`.
+
+    Each UniqueSection implementation class defines a semantically consistent set of settings
+    related to a particular aspect of the application. It differs from a regular `Section` in
+    that it is designed to be unique, meaning only one instance can exist. Each UniqueSection
+    is defined by a section name (related to the objects they configure) and a set of properties.
+
+    Here are the various unique sections in Taipy:
+
+    - `GlobalAppConfig^` for configuring global application settings.
+    - `GuiSection` for configuring the GUI service.
+    - `CoreSection^` for configuring the core package behavior.
+    - `JobConfig^` for configuring the job orchestration.
+    - `AuthenticationConfig^` for configuring authentication settings.
 
-    A UniqueSection is only defined by the section name.
     """
 
     def __init__(self, **properties):

taipy/core/__init__.py

@@ -9,20 +9,25 @@
 # an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
 # specific language governing permissions and limitations under the License.
 
-"""# Taipy Core
+"""# Taipy `core` Package
+
+The Taipy `core` package is a Python library designed to build powerful, customized, data-driven
+back-end applications. It provides the tools to help Python developers transform their algorithms
+into a complete back-end application. In particular, it helps with:
+
+- Data Integration
+- Task Orchestration
+- What-if Analysis
+- Version management
 
-The Taipy Core package is a Python library designed to build powerful, customized, data-driven back-end
-applications. It provides the tools to help Python developers transform their algorithms into a
-complete back-end application.
 More details on the Core functionalities are available in the user manual.
 
-To build a Taipy Core application, the first step consists of setting up the Taipy configuration to design
-your application's characteristics and behaviors.
-Import `Config^` from the `taipy.config^` module, then use the various methods of the `Config^` singleton class to
-configure your core application. In particular, configure the
+To use such functionalities, the first step consists of setting up the Taipy configuration to design
+your application's characteristics and behaviors. Use the `Config^` singleton class (from `taipy.config`)
+to configure your application. Please refer to the
 [data nodes](../../../userman/scenario_features/data-integration/data-node-config.md),
 [tasks](../../../userman/scenario_features/task-orchestration/scenario-config.md),
-and [scenarios](../../../userman/scenario_features/sdm/scenario/scenario-config.md).
+and [scenarios](../../../userman/scenario_features/sdm/scenario/scenario-config.md) pages.
 
 Once your application is configured, import module `import taipy as tp` so you can use any function described
 in the following section on [Function](#functions). In particular, the most used functions are `tp.create_scenario()`,

taipy/core/_core.py

@@ -16,7 +16,7 @@
 
 
 class Core:
-    """Deprecated. Use the `Orchestrator^` service class with `taipy.Orchestrator()` instead."""
+    """Deprecated. Use the `Orchestrator^` service class instead."""
 
     __logger = _TaipyLogger._get_logger()
 

taipy/core/_init.py

@@ -27,6 +27,7 @@
 from .submission.submission_id import SubmissionId
 from .submission.submission_status import SubmissionStatus
 from .taipy import (
+    can_create,
     cancel_job,
     clean_all_entities,
     clean_all_entities_by_version,