[Enhancement] Improve and clarify the help documentation for the command line tools

[Leemur89]

Describe the bug
Hello,
When using the enabled parameter in my robot.toml, my profile is not enabled

To Reproduce
Steps to reproduce the behavior:
robot.toml:

[profiles.ci]
description = "CI pipelines"
enabled = true

Then using robotcode:

$ robotcode profiles list
  Active   Selected   Enabled   Precedence   Name   Description   
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
                                             ci     CI pipelines  

Expected behavior
Profile is enabled

Desktop (please complete the following information):
VS Code Version 1.89.1
RobotCode Version 0.85.0
OS: MacOS Ventura 13.3.1
Python Version 3.8.19
RobotFramework Version 7.0.1
robotframework-browser 18.7.0
robotframework-robocop 5.3.0
robotcode-runner 0.85.0

[Leemur89]

ok after digging a bit inside the code I understood: it will only be enabled if we select it with the option -p
I find it a bit counter intuitive, I would have expected it to be selected when enabled is true, for instance from my ci:

robotcode profiles list

would show my ci profile as enabled

But actually I need:

robotcode -p ci profiles list

[d-biehl]

The functionality works as designed. A profile must be selected, and once it is selected, it is evaluated and potentially combined with other selected profiles.

To set specific profiles as default so that you don't have to specify them each time you start, you can use the default-profiles setting.

A profile is activated by default, but whether it is truly active in a particular configuration is determined – as you have already discovered – by either selecting the profile via -p or by defining it in the default-profiles entry in robot.toml. You can also use expressions to calculate whether a profile is activated or not, and you might set certain environment variables within a profile that are then evaluated, and so on.

Take this robot.toml as an example:

default-profiles = ["ci", "test", "prod", "devel"]

[profiles.ci]
enabled = { if = 'environ.get("CI", None) == "1"' }
inherits = ["headless"]

[profiles.ci.env]
IN_CI = "1"

[profiles.headless]
enabled = { if = 'environ.get("IN_CI", "0") == "1"' }
precedence = 100

[profiles.headless.extend-variables]
HEADLESS = "ON"

[profiles.prod]
enabled = { if = 'environ.get("CI_ENV", None) == "Prod"' }

[profiles.prod.extend-variables]
URL = "https://prod.example.com"

[profiles.devel.extend-variables]
URL = "https://devel.example.com"

[profiles.test]
enabled = { if = 'environ.get("CI_ENV", None) == "Test"' }

[profiles.test.extend-variables]
URL = "https://test.example.com"

In this file, we define several profiles that are enabled or disabled depending on certain environment variables. A special case is the ci profile, where we define an environment variable that is used in the headless profile.

This allows us to define complex configurations in robot.toml, while controlling what actually happens via environment variables, similar to how it is done in CI environments.

I know there is still a lot of documentation missing on this whole topic, but I am working on it. I'll leave this bug open for now, but I will turn it into an enhancement to improve the documentation, specifically for the command line tools.

[Leemur89]

Thanks I understand a bit better now

From what you explained I understand that the enabled is only evaluated when profile is selected.
And selected means that it is either default or selected via the -p option.
Then what does active mean?
Is it "Active = Selected AND Enabled" ?

[d-biehl]

exactly ;-)

[Leemur89]

In that case shouldn't enabled be ticked when listing the profiles?

$ robotcode profiles list
  Active   Selected   Enabled   Precedence   Name   Description   
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
                                             ci     CI pipelines  

Also another question: if I have some default profiles (e.g. ci), but when I run via CLI I select the profile (e.g.g -p dryrun), will it override the default profile (dryrun only), or is it cumulative(dryrun + ci)?

[d-biehl]

In that case shouldn't enabled be ticked when listing the profiles?

no, because it was not evaluated because it is not selected, maybe we could distinguish whether it is a boolean value in the enabled setting or an expression and display it accordingly. I'll have to think about it...

Also another question: if I have some default profiles (e.g. ci), but when I run via CLI I select the profile (e.g.g -p dryrun), will it override the default profile (dryrun only), or is it cumulative(dryrun + ci)?

it is overridden, maybe we could introduce a --extend-default-profile switch?