[missing doc] Undocumented side-effect and parameter auto_generate

[araffin]

By default, conan2 uses VirtualRunEnv and VirtualBuildEnv generators (this is briefly mentioned but is missing from the VirtualRunEnv doc).

However, if a generator (or anything from the top conanfile) instantiates VirtualRunEnv (or VirtualBuildEnv) for its own use, this will have a side effect, prevent the default behavior and VirtualRunEnv.generate() will never be called (so conanrun.sh won't be present).

A solution is to use the undocumented parameter auto_generate=True or to explicitly call self.virtual_run_env.generate() everytime VirtualRunEnv() is instantiated.

It would be nice to document the parameter, default behavior and side effect (if intended).

Relevant code:
https://github.com/conan-io/conan/blob/ad0b39c228ecb6b5539fb5995c7a3e98f85c9bf9/conan/tools/env/virtualrunenv.py#L39-L40

The behavior was introduced in conan-io/conan#9543

How to reproduce it

from conan.tools.env import VirtualBuildEnv, VirtualRunEnv

class MyGenerator:
    def __init__(self, conanfile):
        self._conanfile = conanfile
        # This will prevent `conanrun.sh` to be generated
        self.virtual_run_env = VirtualRunEnv(conanfile, auto_generate=False)
        self.virtual_build_env = VirtualBuildEnv(conanfile, auto_generate=False)

    def generate(self):
        pass

[memsharded]

Thanks @araffin for reporting this.

It is true that https://docs.conan.io/2/reference/tools/env/virtualbuildenv.html#reference shows the argument, but not fully document it.

We added the argument to allow our usage to not cause this effect, but we are also reconsidering if instantiating directly these generators elsewhere for the purpose of aggregating env-vars, but not generating environment script files is the way to go. We might refactor these generator into some base classes that don't generate files and can be used everywhere, but this is not fully clear yet.

In general I think it makes sense to think that if VirtualXXXEnv is instantiated by the user somewhere, the default behavior of not generating environment files is good, the user took control of the generation. So lets move it to the docs repo to add some clarification in the docs regarding this behavior and auto_generate, thanks!