update docs

docs/configuration.md

@@ -48,6 +48,7 @@ virtualenvs.in-project = null
 virtualenvs.options.always-copy = true
 virtualenvs.options.always-copy = true
 virtualenvs.options.system-site-packages = false
 virtualenvs.options.system-site-packages = false
 virtualenvs.path = "{cache-dir}/virtualenvs"  # /path/to/cache/directory/virtualenvs
 virtualenvs.path = "{cache-dir}/virtualenvs"  # /path/to/cache/directory/virtualenvs
+virtualenvs.prefer-shell-python = false
 ```
 ```
 
 
 ## Displaying a single configuration setting
 ## Displaying a single configuration setting
@@ -188,6 +189,13 @@ Give the virtual environment access to the system site-packages directory.
 Applies on virtualenv creation.
 Applies on virtualenv creation.
 Defaults to `false`.
 Defaults to `false`.
 
 
+### `virtualenvs.prefer-shell-python`
+
+**Type**: boolean
+
+Use currently activated Python version to create a new venv.
+Defaults to `false`, which means Python version used during Poetry installation is used.
+
 ### `repositories.<name>`
 ### `repositories.<name>`
 
 
 **Type**: string
 **Type**: string

docs/managing-environments.md

@@ -18,7 +18,7 @@ To achieve this, it will first check if it's currently running inside a virtual
 If it is, it will use it directly without creating a new one. But if it's not, it will use
 If it is, it will use it directly without creating a new one. But if it's not, it will use
 one that it has already created or create a brand new one for you.
 one that it has already created or create a brand new one for you.
 
 
-By default, Poetry will try to use the currently activated Python version
+By default, Poetry will try to use the Python version used during Poetry's installation
 to create the virtual environment for the current project.
 to create the virtual environment for the current project.
 
 
 However, for various reasons, this Python version might not be compatible
 However, for various reasons, this Python version might not be compatible
@@ -26,6 +26,21 @@ with the `python` requirement of the project. In this case, Poetry will try
 to find one that is and use it. If it's unable to do so then you will be prompted
 to find one that is and use it. If it's unable to do so then you will be prompted
 to activate one explicitly, see [Switching environments](#switching-between-environments).
 to activate one explicitly, see [Switching environments](#switching-between-environments).
 
 
+{{% note %}}
+To easily switch between Python versions, it is recommended to
+use [pyenv](https://github.com/pyenv/pyenv) or similar tools.
+
+For instance, if your project requires a newer Python than is available with
+your system, a standard workflow would be:
+
+```bash
+pyenv install 3.9.8
+pyenv local 3.9.8  # Activate Python 3.9 for the current project
+poetry install
+```
+This requires setting the `virtualenvs.prefer-shell-python` option to `true`.
+{{% /note %}}
+
 ## Switching between environments
 ## Switching between environments
 
 
 Sometimes this might not be feasible for your system, especially Windows where `pyenv`
 Sometimes this might not be feasible for your system, especially Windows where `pyenv`