docs: update some documentation about config and cli

Author: d-biehl

docs/02_get_started/configuration.md

@@ -1,260 +1,143 @@
 # Configuration
 
-## Introducing the `robot.toml` file
+## Introduction to the `robot.toml` File
 
-The `robot.toml` file offers an alternative way of setting up your project in VS Code. Usually, those settings  would be done via the `settings.json` file, doing so comes though at the cost of several limitations and inconveniences. Using `robot. toml` alleviates many of those by:
+The `robot.toml` file provides a structured and flexible way to configure your Robot Framework project. Rather than relying on various argument files, batch files or command-line arguments, you can consolidate all key settings in this one centralized file. This makes it easier to manage and maintain settings across different environments and use cases.
 
-- providing a simpler way of defining settings for the Robot Framework project in one file
-- creating a file that can be easily shared and uploaded to a git repository
-- removing the need to create an argument file
-- simplifying the command line execution
-- allowing to define multiple, easily expandable, profiles
+Similar to how `pyproject.toml` has become a standard for configuring Python projects, the `robot.toml` file aims to serve the same role for Robot Framework projects. It allows you to define project settings such as output directories, environment variables, and profiles for different testing scenarios. This unified configuration approach simplifies project management and makes it easier to share and version control configurations.
 
-::: info
-The following documentation serves as a quick introduction on how to use the `robot.toml` file and will not cover all *Robot Framework* command line options. For a complete documentation of these options, please refer to the [Robot Framework User Guide](https://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html "Robot Framework User Guide").
-:::
+While the `robot.toml` file can be integrated with development environments like VS Code, its primary function is to centralize configuration for Robot Framework projects, streamlining the setup and maintenance process.
 
-::: tip
-If you want to have code completion and such things for TOML files, install the **[Even Better TOML](https://marketplace.visualstudio.com/items?itemName=tamasfe.even-better-toml)** extension before attempting to work with `robot.toml`.
-:::
+This guide provides an overview of how to set up and use the `robot.toml` file to manage various aspects of your Robot Framework project.
 
+---
 
-## Settings configuration
+## About TOML Files
 
-Using the `robot.toml` file, we can configure a wide range of settings for our project. The example below shows how we can setup the output directory, language and global project variables. In toml, `[variables]` is a tabular setting, meaning it can store multiple name-value pairs.
+TOML (Tom's Obvious, Minimal Language) is a file format designed to be easy to read and write due to its clear structure. TOML files use key-value pairs to define configuration settings, similar to JSON or YAML, but with a more human-friendly syntax. In the context of the `robot.toml` file, TOML is used to structure the configuration settings for your Robot Framework project, allowing for well-organized and readable project settings.
 
-```toml
-output-dir = "output"
-languages = ["english"]
-
-[variables]
-NAME = "Tim"
-AGE = "25"
-MAIL = "hotmail.de"
-```
-
-You can access a full list of available setting by excetuting `robot --help` in the CLI.
-
-
-## Profiles
-
-Profiles allow you to store multiple configurations, in an easily accessible way. This can be useful if for example you need a different set of configurations, for testing on multiple platforms. Profiles are easily expandable and can be easily shared between developers by simply providing them the robot.toml file.
-
-
-### Defining profiles
-
-You can define a profile with `[profiles.YOUR_PROFILE_NAME]`. Follow it up with the settings that you want to configure for that particular profile. For tabular settings like `[variables]` you will need to create a separate entry using `[profiles.YOUR_PROFILE_NAME.variables]`. Your profiles will use any global configuration, that has not been defined within the profile. In example below, dev2 will use English as the language and *output* as the output directory.
-
-```toml
-output-dir = "output"
-languages = ["english"]
-
-[variables]
-NAME = "Tim"
-AGE = "25"
-MAIL = "hotmail.de"
-
-[profiles.dev1]
-output-dir = "dev1output"
-languages = ["german"]
-
-[profiles.dev1.variables]
-NAME = "Lisa"
-AGE = "32"
-MAIL = "web.de"
-
-[profiles.dev2.variables]
-NAME = "Andrew"
-AGE = "19"
-MAIL = "gmail.com"
-
-[profiles.dev3]
-output-dir = "dev3output"
-```
+For a full and detailed description of the TOML format, please refer to the official [TOML documentation](https://toml.io/en/).
 
+---
 
-### Overriding and extending settings
+## Configuring Settings
 
-Tabular settings like `[variables]` can be either overridden or expanded. In the example below, dev1 and dev2 are overriding `[variables]`. Override will prevent dev1 and dev2 from using any of the values defined in lines 4-7. This means that dev2 will not use  `NAME = "Tim"` defined in line 5 but instead whatever is defined in the relevant .robot files.
+The `robot.toml` file allows you to configure various settings for your project. Below is an example that demonstrates how to configure the output directory, language preferences, and some global project variables. In TOML, `[variables]` is used to store multiple name-value pairs.
 
 ```toml
 output-dir = "output"
-languages = ["english"]
+languages = ["en", "fi"]
 
 [variables]
 NAME = "Tim"
 AGE = "25"
 MAIL = "hotmail.de"
-
-[profiles.dev1.variables]
-NAME = "Lisa"
-AGE = "32"
-MAIL = "web.de"
-
-[profiles.dev2.variables]
-AGE = "19"
-MAIL = "gmail.com"
 ```
 
-In order to change only selected values or add new ones, the 'extend-' prefix is needed. In the example below, dev2 will still use `NAME` and `AGE` defined in lines 2 and 3.
+The key concept is that for every option you can set via the command line in a `robot` call, there is a corresponding key in the `robot.toml` file. Options that can be specified multiple times, such as `--variable` or `--tag`, are stored as lists. To view all available options, you can run `robot --help` in the command line or refer
 
-```toml
-[variables]
-NAME = "Tim"
-AGE = "25"
-MAIL = "hotmail.de"
-
-[profiles.dev2.extend-variables]
-MAIL = "gmail.com"
-LOCATION = "Berlin"
-```
+For better readability, multi-word options are written with hyphens in the `robot.toml` file. For example, `--outputdir` becomes `output-dir`. In addition to standard command-line options, the `robot.toml` file offers additional configuration settings. To view the full list, you can run the `robotcode config info` command or consult the [Configuration Reference](../03_reference/config.md).
 
 
-### Inheriting and merging profiles
+## Profiles
 
-Profiles can inherit from an already existing profile.
+Profiles in the `robot.toml` file allow you to store multiple configurations in an easily accessible way. This is particularly helpful when you need different settings for various testing environments, such as different platforms or testing conditions.
 
-```toml
-[profiles.dev3]
-output-dir = "dev3output"
+### Example of Profiles
 
-[profiles.inheritedFromDev3]
-inherits = ["dev3"]
-languages = ["german"]
-```
-
-It is also possible to inherit from multiple profiles.
+Below is an example showing how to set up two profiles: `dev` and `prod`, each with distinct settings.
 
 ```toml
-[profiles.dev1]
-output-dir = "dev1output"
-languages = ["german"]
-
-[profiles.dev1.variables]
-NAME = "Lisa"
-AGE = "32"
-MAIL = "web.de"
+[profiles.dev]
+output-dir = "output/dev"
+variables = { NAME = "Developer" }
 
-[profiles.dev3]
-output-dir = "dev3output"
-
-[profiles.dev1and3]
-inherits = ["dev1, dev3"]
+[profiles.prod]
+output-dir = "output/prod"
+variables = { NAME = "Production" }
 ```
 
-If a variable is present in multiple of the inherited profiles, the value of that variable will be the one, present in the last relevant inherited profile. In the example above, the value of `output-dir` for the dev1and2 profile, will be "dev3output".
-
-
-### Profile management
-
-#### Selecting profiles
-
-You can select a profile to work with, by entering "RobotCode: Select Configuration Profiles" in the command palette (ctrl+shift+p).
+### Inheriting Profiles
 
-![Select Profile1](images/toml-profiles-command-selection.png)
-
-Should you select more than one profile, a merged version of those profiles will be executed.
-Alternatively, you can select a profile to run or debug with, by clicking on the buttons, marked in the image below.
-
-![Select Profile2](images/config_select_buttons.png)
-
-Using this method however, does not allow you to select multiple profiles at once.
-
-
-#### Default profiles
-
-It is possible to select a list of default profiles, using the `default-profiles` option. Those profiles will be selected by default, if no other profile has been selected for execution.
-Should you select more than one default profile, a merged version of those profiles will be executed.
+Profiles can also inherit settings from each other to reduce duplication. The `merge` keyword allows you to combine settings from multiple profiles.
 
 ```toml
-default-profiles = ["dev1", "dev2"]
-
-[profiles.dev1.variables]
-NAME = "Lisa"
-AGE = "32"
-MAIL = "web.de"
-
-[profiles.dev2.variables]
-AGE = "19"
-MAIL = "gmail.com"
-
-[profiles.dev3.variables]
-MAIL = "hotmail.com"
+[profiles.shared]
+output-dir = "output/shared"
 
+[profiles.dev]
+merge = ["shared"]
+variables = { NAME = "Dev" }
 ```
 
+### Hiding Profiles
 
-#### Hiding profiles
-
-If, for whatever reason, you wish for individual profiles to not be displayed as selectable options, you can hide them by using the `hidden` option.
+Profiles can be hidden using the `hidden` option or based on specific conditions through Python expressions.
 
 ```toml
-[profiles.dev1]
+[profiles.dev]
 hidden = true
-```
-
-It is also possible to hide a profile based on user defined conditions, using python expressions.
 
-```toml
-[profiles.dev1]
+[profiles.dev]
 hidden.if = "platform.system()=='Windows'"
 ```
 
-Hidden profiles can be still merged and inherited from.
-
+### Enabling Profiles
 
-#### Enabling profiles
-
-Similar to hiding, profiles can be also disabled using the `enabled` option.
+Similarly, profiles can be enabled or disabled using the `enabled` option. This can also be based on user-defined conditions.
 
 ```toml
-[profiles.dev1]
+[profiles.dev]
 enabled = false
-```
 
-It is also possible to enable or disable a profile based on user defined conditions, using python expressions.
-
-```toml
-[profiles.dev1]
+[profiles.dev]
 enabled.if = "platform.system()=='Windows'"
 ```
 
 Disabled profiles cannot be merged or inherited from.
 
+---
 
-### Test Execution
-
-In order to execute tests using the CLI, you will need to install the `robotcode-runner` pip package and add it to your requirements.txt.
-
-
-#### Executing tests
-
-Here are some of the most common ways, to execute tests via the CLI.
-
-
-- `robotcode robot PATH`
-
-  Executes all tests (including in subfolders) within a given location. This command can be also executed with the command `robotcode robot`, if you add `paths = "TESTFILE_LOC"` to your robot.toml file.
-
-- `robotcode robot -t "TEST_CASE_NAME"`
-
-  Executes the test case called `TEST_CASE_NAME`
+## Test Execution
 
-- `robotcode -p PROFILE_NAME robot PATH`
+To execute tests using the CLI, ensure that the `robotcode-runner` pip package is installed and added to your `requirements.txt` file.
 
-  Executes all tests (including in subfolders) within a given location, with the selected profile.
+### Executing Tests
 
-- `robotcode -p PROFILE_NAME_1  -p PROFILE_NAME_2 robot PATH`
+Here are some common ways to execute tests using the CLI:
 
-  Executes all tests (including in subfolders) within a given location, with a merged version the selected profiles.
+- Execute all tests within a location:
+  ```bash
+  robotcode robot PATH
+  ```
+  Alternatively, you can specify paths in the `robot.toml` file:
+  ```toml
+  paths = "TESTFILE_LOC"
+  ```
 
-- `robotcode -p PROFILE_NAME -v NAME:Carl robot PATH`
+- Execute a specific test case:
+  ```bash
+  robotcode robot -t "TEST_CASE_NAME"
+  ```
 
-  Executes all tests (including in subfolders) within a given location. Changes the value of the variable `NAME` to `Carl`.
+- Execute tests with a specific profile:
+  ```bash
+  robotcode -p PROFILE_NAME robot PATH
+  ```
 
+- Merge and execute tests from multiple profiles:
+  ```bash
+  robotcode -p PROFILE_NAME_1 -p PROFILE_NAME_2 robot PATH
+  ```
 
-- `robotcode robot -i TAG_NAME`
+- Execute tests with a variable override:
+  ```bash
+  robotcode -p PROFILE_NAME -v NAME:Carl robot PATH
+  ```
 
-    Executes all tests with a given tag. Tags can be assigned either globally in the settings or individually for each test case.
+- Execute tests by tag:
+  ```bash
+  robotcode robot -i TAG_NAME
+  ```
 
-    <IMG src="images/tags_robot.PNG"/>
+Tags can be set globally or individually for each test case.