doc: update get started/configuration

Author: d-biehl

docs/02_get_started/configuration.md

@@ -2,142 +2,236 @@
 
 ## Introduction to the `robot.toml` File
 
-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.
+The `robot.toml` file serves as a centralized configuration system for your Robot Framework projects. Instead of managing multiple argument files, batch scripts, or command-line parameters, you can define all your project settings in one structured file.
 
-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.
+Similar to how `pyproject.toml` has become the standard for Python project configuration, `robot.toml` aims to provide the same benefits for Robot Framework projects by:
 
-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.
+- Centralizing all configuration in one location
+- Making settings easily shareable through version control
+- Supporting different environments through profiles
+- Providing a clear, readable format for configuration
 
-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.
-
----
+While fully compatible with development environments like VS Code, the `robot.toml` file is primarily designed to simplify Robot Framework project setup and maintenance.
 
 ## About TOML Files
 
-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 (Tom's Obvious, Minimal Language) is a configuration file format designed to be easy to read and write. It uses simple key-value pairs organized into sections, making it more human-friendly than formats like JSON or XML.
+
+Example of TOML syntax:
+```toml
+# This is a comment
+key = "value"
+
+[section]
+nested_key = "nested value"
+```
 
-For a full and detailed description of the TOML format, please refer to the official [TOML documentation](https://toml.io/en/).
+For full details on TOML syntax, visit the [official TOML documentation](https://toml.io/en/).
 
----
+## Basic Configuration
 
-## Configuring Settings
+### Core Settings
 
-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.
+Every command-line option available in Robot Framework can be configured in your `robot.toml` file:
 
 ```toml
+# Basic settings
 output-dir = "output"
+log-level = "INFO"
 languages = ["en", "fi"]
 
+# Global variables
 [variables]
-NAME = "Tim"
-AGE = "25"
-MAIL = "hotmail.de"
+BROWSER = "Chrome"
+LOGIN_URL = "https://example.com/login"
+TIMEOUT = "20s"
 ```
 
-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
+Multi-word options use hyphens in `robot.toml` (e.g., `--outputdir` becomes `output-dir`).
 
-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).
+To see all available options:
+- Run `robot --help` for standard Robot Framework options
+- Run `robotcode config info` for RobotCode-specific options
+- Check the [Configuration Reference](../03_reference/config.md) documentation
 
+## Working with Profiles
 
-## Profiles
+Profiles allow you to define multiple configurations for different environments or testing scenarios.
 
-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.
-
-### Example of Profiles
-
-Below is an example showing how to set up two profiles: `dev` and `prod`, each with distinct settings.
+### Creating Basic Profiles
 
 ```toml
+# Default settings (applies to all profiles)
+output-dir = "results"
+log-level = "INFO"
+
+# Development environment profile
 [profiles.dev]
-output-dir = "output/dev"
-variables = { NAME = "Developer" }
+output-dir = "results/dev"
+variables = { ENVIRONMENT = "development", API_URL = "http://dev-api.example.com" }
 
+# Production testing profile
 [profiles.prod]
-output-dir = "output/prod"
-variables = { NAME = "Production" }
+output-dir = "results/prod"
+variables = { ENVIRONMENT = "production", API_URL = "https://api.example.com" }
 ```
 
-### Inheriting Profiles
+### Profile Inheritance
 
-Profiles can also inherit settings from each other to reduce duplication. The `inherits` keyword allows you to combine settings from multiple profiles.
+Profiles can inherit settings from other profiles to avoid duplication:
 
 ```toml
-[profiles.shared]
-output-dir = "output/shared"
+# Base profile with common settings
+[profiles.base]
+log-level = "INFO"
+variables = { TIMEOUT = "20s" }
 
+# Development profile builds on base settings
 [profiles.dev]
-inherits = ["shared"]
-variables = { NAME = "Dev" }
+inherits = ["base"]
+variables = { ENVIRONMENT = "development", API_URL = "http://dev-api.example.com" }
+
+# Testing profile also builds on base settings
+[profiles.test]
+inherits = ["base"]
+variables = { ENVIRONMENT = "testing", API_URL = "http://test-api.example.com" }
 ```
 
-### Hiding Profiles
+### Conditional Profiles
 
-Profiles can be hidden using the `hidden` option or based on specific conditions through Python expressions.
+Profiles can be hidden or enabled based on conditions:
 
 ```toml
-[profiles.dev]
+# Hidden profile (not shown in listings)
+[profiles.internal]
 hidden = true
 
-[profiles.dev]
-hidden.if = "platform.system()=='Windows'"
+# Conditionally enabled profiles
+[profiles.windows]
+enabled.if = "platform.system() == 'Windows'"
+variables = { DRIVER_PATH = "C:\\drivers" }
+
+[profiles.linux]
+enabled.if = "platform.system() == 'Linux'"
+variables = { DRIVER_PATH = "/usr/local/bin" }
 ```
 
-### Enabling Profiles
+### Profile Precedence
 
-Similarly, profiles can be enabled or disabled using the `enabled` option. This can also be based on user-defined conditions.
+When multiple profiles are used together, you can control which settings take priority:
 
 ```toml
-[profiles.dev]
-enabled = false
+# Base settings (low precedence)
+[profiles.base]
+variables = { LOG_LEVEL = "INFO", BROWSER = "chrome" }
+
+# Override with higher precedence
+[profiles.debug]
+precedence = 100
+variables = { LOG_LEVEL = "DEBUG" }
+
+# Highest priority settings
+[profiles.critical]
+precedence = 200
+variables = { RETRIES = 3 }
+```
 
-[profiles.dev]
-enabled.if = "platform.system()=='Windows'"
+## Test Execution
+
+### Running Tests with RobotCode
+
+To execute tests, install the `robotcode-runner` package:
+
+```bash
+pip install robotcode[runner]
 ```
 
-Disabled profiles cannot be merged or inherited from.
+Common test execution commands:
 
----
+```bash
+# Run all tests in a directory
+robotcode robot tests/
 
-## Test Execution
+# Run with a specific profile
+robotcode -p dev robot tests/
+
+# Combine multiple profiles
+robotcode -p base -p windows robot tests/
+
+# Override variables on command line
+robotcode -p dev -v BROWSER:firefox robot tests/
+
+# Run tests by tag
+robotcode robot -i smoke -i regression tests/
+```
+
+You can also define paths directly in the configuration:
+
+```toml
+paths = ["tests"]
+
+```
 
-To execute tests using the CLI, ensure that the `robotcode-runner` pip package is installed and added to your `requirements.txt` file.
+then it is not needed to give specific paths at the commandline, just type:
+
+```bash
+# run all tests
+robotcode run
+
+# run tests and only include/exclude tests with specific tags
+robotcode run -i regression -e wip
+```
+
+## Advanced Configuration
+
+### Extending vs. Replacing Settings
+
+By default, when merging profiles, list and dictionary settings are completely replaced. To add to these settings instead, use the `extend-` prefix:
+
+```toml
+# Default settings
+variables = { BROWSER = "chrome", TIMEOUT = "20s" }
+include = ["smoke"]
+
+[profiles.api]
+# Completely replaces the default variables
+variables = { API_KEY = "123456" }  # BROWSER and TIMEOUT are removed
+
+[profiles.extended]
+# Adds to the default variables
+extend-variables = { API_KEY = "123456" }  # Results in {BROWSER = "chrome", TIMEOUT = "20s", API_KEY = "123456"}
+extend-include = ["api"]  # Results in ["smoke", "api"]
+```
 
-### Executing Tests
+Settings that support the `extend-` prefix include:
+- `variables`
+- `include` / `exclude`
+- `python-path`
+- `metadata`
 
-Here are some common ways to execute tests using the CLI:
+and many more, see the [`robot.toml` reference](../03_reference/config.md) for all posibilities.
 
-- Execute all tests within a location:
-  ```bash
-  robotcode robot PATH
-  ```
-  Alternatively, you can specify paths in the `robot.toml` file:
-  ```toml
-  paths = "TESTFILE_LOC"
-  ```
+## Configuration Loading Order
 
-- Execute a specific test case:
-  ```bash
-  robotcode robot -t "TEST_CASE_NAME"
-  ```
+RobotCode loads configuration files in a specific sequence, with each file potentially overriding settings from previous ones:
 
-- Execute tests with a specific profile:
-  ```bash
-  robotcode -p PROFILE_NAME robot PATH
-  ```
+1. **Global user configuration**
+   - Located at `~/.robot.toml` (user's home directory)
+   - Sets system-wide defaults
 
-- Merge and execute tests from multiple profiles:
-  ```bash
-  robotcode -p PROFILE_NAME_1 -p PROFILE_NAME_2 robot PATH
-  ```
+2. **Project `pyproject.toml`**
+   - Located in the project root
+   - Robot settings stored in the `[tool.robot]` section
 
-- Execute tests with a variable override:
-  ```bash
-  robotcode -p PROFILE_NAME -v NAME:Carl robot PATH
-  ```
+3. **Project `robot.toml`**
+   - Located in the project root
+   - Main project configuration (should be in version control)
 
-- Execute tests by tag:
-  ```bash
-  robotcode robot -i TAG_NAME
-  ```
+4. **Personal `.robot.toml`**
+   - Located in the project root
+   - User-specific overrides (should be added to `.gitignore`)
 
-Tags can be set globally or individually for each test case.
+When multiple profiles are specified, they're applied in this order:
+1. Default settings (top-level settings not in any profile)
+2. Profiles ordered by precedence (lowest to highest)
+3. For equal precedence, the order specified on the command line