dotenv new feature (#4246)

Author: memsharded

reference/tools/env/environment.rst

@@ -38,6 +38,28 @@ by default, but the ``separator`` argument can be provided to define a custom on
 The "path" variables (the ones declared with ``define_path``, ``append_path`` and ``prepend_path``) will be appended
 with the default system path separator, either ``:`` or ``;``, but it also allows defining which one.
 
+Generation of environment files
++++++++++++++++++++++++++++++++
+
+The generation of environment script files (like ``envfile.bat|.sh|.ps1|.env``) can be done indirectly
+by the ``EnvVars`` class, which can be obtained with:
+
+.. code:: python
+
+    from conan.tools.env import Environment
+
+    env1 = Environment()
+    ...
+    envvars = env1.vars(self)  # An EnvVars object
+    # Generate a .bat|.sh|.ps1|.env file depending on current
+    # settings and Conan configuration
+    envars.save_script("mybuild")
+    # or decide to be explicit and generate some of the files:
+    envvars.save_dotenv("myenv.env")
+
+These files can be used also automatically by subsequent ``self.run()`` calls.
+For more information see the ``EnvVars`` class documentation.
+
 
 Composition
 +++++++++++

reference/tools/env/envvars.rst

@@ -58,6 +58,11 @@ aggregate and create a ``conanrun.bat|sh|ps1`` script:
         envvars.save_script("my_env_file")
 
 
+From Conan 2.21, if the **experimental** ``tools.env:dotenv`` configuration is active, then
+``.env`` files will also be generated. These files are not intended to be activated as scripts,
+but loaded by tools such as IDEs.
+
+
 You can also use ``scope=None`` argument to avoid appending the script to the aggregated ``conanbuild.bat|sh|ps1``:
 
 .. code:: python

reference/tools/env/virtualbuildenv.rst

@@ -95,6 +95,18 @@ will create the following files:
     or ``False`` is deprecated as of Conan 2.11.0 and should no longer be used.
 
 
+.. note::
+
+    To create ``.env`` dotenv files, use the **experimental** (new in Conan 2.21) ``tools.env:dotenv`` configuration.
+    These files are not intended to be activated as scripts, but loaded by tools such as IDEs.
+    The configuration specific files such as ``conanbuildenv-Release.env`` will be generated, as the
+    environment can be different for Release and Debug configurations.
+    These files at the moment do not use variable interpolation due to some VScode limitations, 
+    a warning is printed pointing to https://github.com/microsoft/vscode-cpptools/issues/13781 to
+    track progress. 
+    Please open a Github ticket to report any feedback about this feature.
+
+
 .. note::
 
     Disabling the automatic generation of these files for consumers can be achieved by passing ``--envs-generation=false`` to the ``conan install`` command.

reference/tools/env/virtualrunenv.rst

@@ -67,6 +67,17 @@ current active configuration, like ``deactivate_conanrunenv-release-x86_64.bat``
     executable (e.g., ``powershell.exe`` or ``pwsh``). Note that, setting it to ``True``
     or ``False`` is deprecated as of Conan 2.11.0 and should no longer be used.
 
+.. note::
+
+    To create ``.env`` dotenv files, use the **experimental** (new in Conan 2.21) ``tools.env:dotenv`` configuration.
+    These files are not intended to be activated as scripts, but loaded by tools such as IDEs.
+    The configuration specific files such as ``conanrunenv-Release.env`` will be generated, as the
+    environment can be different for Release and Debug configurations.
+    These files at the moment do not use variable interpolation due to some VScode limitations, 
+    a warning is printed pointing to https://github.com/microsoft/vscode-cpptools/issues/13781 to
+    track progress. 
+    Please open a Github ticket to report any feedback about this feature.
+
 .. note::
 
     Disabling the automatic generation of these files for consumers can be achieved by passing ``--env-generation=false`` to the ``conan install`` command.