Improve ref man (#1827)

* Improve ref man

* Update config.pyi

* Improve ref man

* Apply suggestions from code review

Apply Fabien's feedback

Co-authored-by: Fabien Lelaquais <86590727+FabienLelaquais@users.noreply.github.com>

* Update config.pyi

* Update taipy/config/section.py

* Table cell bool rendering (#1825)

* Table cell bool rendering
commanded by light_bool_render
resolves #662

* change in edit mode too

* use_checkbox

* support lov for boolean

* send lov when necessary only

* useCheckbox

* protect colDesc.type

---------

Co-authored-by: Fred Lefévère-Laoide <Fred.Lefevere-Laoide@Taipy.io>

* Handle default values

* Handle default values that are not Python expressions

* Replace entrypoint by class

* Update config.pyi

---------

Co-authored-by: jrobinAV <jrobinAV@users.noreply.github.com>
Co-authored-by: Fabien Lelaquais <86590727+FabienLelaquais@users.noreply.github.com>
Co-authored-by: Fred Lefévère-Laoide <90181748+FredLL-Avaiga@users.noreply.github.com>
Co-authored-by: Fred Lefévère-Laoide <Fred.Lefevere-Laoide@Taipy.io>
Co-authored-by: Fabien Lelaquais <fabien.lelaquais@avaiga.com>

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 @@ from typing import Any, Optional
 
 @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 @@ from .issue import Issue
 
 
 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 @@ 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.
+
+    """
 
     _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 @@ from ..common._template_handler import _TemplateHandler as _tpl
 
 
 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 @@ from .common._validate_id import _validate_id
 
 
 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 @@ from .section import Section
 
 
 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 @@ from .orchestrator import Orchestrator
 
 
 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 import Submission
 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,

taipy/core/config/__init__.py

@@ -8,6 +8,7 @@
 # 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.
+"""Configuration of the core package functionalities."""
 
 from taipy.config import _inject_section
 from taipy.config.checker._checker import _Checker

taipy/core/config/core_section.py

@@ -31,8 +31,7 @@ from ..exceptions.exceptions import ConfigCoreVersionMismatched
 
 
 class CoreSection(UniqueSection):
-    """
-    Configuration parameters for running the `Orchestrator^` service.
+    """Configuration parameters for running the `Orchestrator^` service.
 
     Attributes:
         root_folder (str): Path of the base folder for the taipy application. The default value is "./taipy/"

taipy/core/data/__init__.py

@@ -8,6 +8,7 @@
 # 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.
+"""Classes related to data nodes."""
 
 from .aws_s3 import S3ObjectDataNode
 from .csv import CSVDataNode

taipy/core/exceptions/__init__.py

@@ -8,5 +8,5 @@
 # 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 `core` package functionalities."""
 from .exceptions import *

taipy/core/exceptions/exceptions.py

@@ -13,11 +13,12 @@ from typing import List, Optional
 
 
 class ConfigCoreVersionMismatched(Exception):
-    """Raised if core version in Config does not match with the version of Taipy Core."""
+    """Raised if the version in Config does not match with the version of Taipy Version management."""
 
     def __init__(self, config_core_version: str, core_version: str) -> None:
         self.message = (
-            f"The version {config_core_version} of Core's entities does not match version of Taipy Core {core_version}."
+            f"The version {config_core_version} of Taipy's entities does not match version of the Taipy"
+            f" Version management {core_version}."
             f" Please update the core entities to be compatible with Taipy Core {core_version}"
             " using the `taipy migrate ...` command. For more information, please run `taipy help migrate`"
         )

taipy/core/reason/__init__.py

@@ -8,6 +8,19 @@
 # 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.
+"""Reasons for the Taipy actions why they can't be performed.
+
+Because Taipy applications are natively multiuser, asynchronous, and dynamic,
+some functions should not be invoked in some specific contexts. You can protect
+such calls by calling other methods that return a `ReasonCollection^`. It acts
+like a Boolean value: True if the operation can be performed and False otherwise. If
+the action cannot be performed, the `ReasonCollection^` holds all the individual
+reasons as a list of `Reason^` objects.
+
+This package exposes the `ReasonCollection^` class and all
+the reason implementations that can be used to explain why some Taipy operations
+are not available or allowed.
+"""
 
 from .reason import (
     DataNodeEditInProgress,

taipy/core/reason/reason.py

@@ -13,8 +13,7 @@ from typing import Any, Optional
 
 
 class Reason:
-    """
-    A reason explains why a specific action cannot be performed.
+    """A reason explains why a specific action cannot be performed.
 
     This is a parent class aiming at being implemented by specific sub-classes.
 

taipy/core/reason/reason_collection.py

@@ -15,8 +15,7 @@ from .reason import Reason
 
 
 class ReasonCollection:
-    """
-    This class is used to store all the reasons to explain why some Taipy operations are not allowed.
+    """This class is used to store all the reasons to explain why some Taipy operations are not allowed.
 
     Because Taipy applications are natively multiuser, asynchronous, and dynamic,
     some functions might not be called in some specific contexts. You can protect

taipy/rest/api/__init__.py

@@ -8,7 +8,7 @@
 # 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.
-
+"""Package for the Taipy Rest API."""
 from . import error_handler, views
 
 __all__ = ["views", "error_handler"]