From 084e3a318b13defcb306a91ea186a4051665f4a7 Mon Sep 17 00:00:00 2001 From: Mathieu Kniewallner Date: Sat, 27 Aug 2022 22:55:52 +0200 Subject: [PATCH 1/2] doc(configuration): improve documentation --- docs/configuration.md | 112 ++++++++++++++++++++++++++---------------- 1 file changed, 71 insertions(+), 41 deletions(-) diff --git a/docs/configuration.md b/docs/configuration.md index 50410f43de8..ef74f3456af 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -147,7 +147,7 @@ You can override the Cache directory by setting the `POETRY_CACHE_DIR` environme ### `cache-dir` -**Type**: string +**Type**: `string` The path to the cache directory used by Poetry. @@ -159,7 +159,9 @@ Defaults to one of the following directories: ### `experimental.system-git-client` -**Type**: boolean +**Type**: `boolean` + +**Default**: `false` *Introduced in 1.2.0* @@ -169,33 +171,40 @@ Poetry uses `dulwich` by default for git related tasks to not rely on the availa If you encounter any problems with it, set to `true` to use the system git backend. -Defaults to `false`. - ### `installer.parallel` -**Type**: boolean +**Type**: `boolean` + +**Default**: `true` + +*Introduced in 1.1.4* Use parallel execution when using the new (`>=1.1.0`) installer. -Defaults to `true`. ### `installer.max-workers` -**Type**: int +**Type**: `int` + +**Default**: `number_of_cores + 4` + +*Introduced in 1.2.0* -Set the maximum number of workers while using the parallel installer. Defaults to `number_of_cores + 4`. +Set the maximum number of workers while using the parallel installer. The `number_of_cores` is determined by `os.cpu_count()`. -If this raises a `NotImplentedError` exception `number_of_cores` is assumed to be 1. +If this raises a `NotImplementedError` exception, `number_of_cores` is assumed to be 1. If this configuration parameter is set to a value greater than `number_of_cores + 4`, the number of maximum workers is still limited at `number_of_cores + 4`. {{% note %}} -This configuration will be ignored when `installer.parallel` is set to false. +This configuration is ignored when `installer.parallel` is set to `false`. {{% /note %}} ### `installer.no-binary` -**Type**: string | bool +**Type**: `string | boolean` + +**Default**: `false` *Introduced in 1.2.0* @@ -243,19 +252,21 @@ across all your projects if incorrectly set. ### `virtualenvs.create` -**Type**: boolean +**Type**: `boolean` + +**Default**: `true` Create a new virtual environment if one doesn't already exist. -Defaults to `true`. If set to `false`, poetry will install dependencies into the current python environment. ### `virtualenvs.in-project` -**Type**: boolean +**Type**: `boolean` + +**Default**: `None` Create the virtualenv inside the project's root directory. -Defaults to `None`. If not set explicitly, `poetry` by default will create virtual environment under `{cache-dir}/virtualenvs` or use the `{project-dir}/.venv` directory when one is available. @@ -267,33 +278,44 @@ If set to `false`, `poetry` will ignore any existing `.venv` directory. ### `virtualenvs.path` -**Type**: string +**Type**: `string` + +**Default**: `{cache-dir}/virtualenvs` Directory where virtual environments will be created. -Defaults to `{cache-dir}/virtualenvs` (`{cache-dir}\virtualenvs` on Windows). ### `virtualenvs.prompt` -**Type**: string +**Type**: `string` + +**Default**: `{project_name}-py{python_version}` + +*Introduced in 1.2.0* Format string defining the prompt to be displayed when the virtual environment is activated. The variables `project_name` and `python_version` are available for formatting. -Defaults to `"{project_name}-py{python_version}"`. ### `virtualenvs.options.always-copy` -**Type**: boolean +**Type**: `boolean` -If set to `true` the `--always-copy` parameter is passed to `virtualenv` on creation of the venv. Thus all needed files are copied into the venv instead of symlinked. -Defaults to `false`. +**Default**: `false` + +*Introduced in 1.2.0* + +If set to `true` the `--always-copy` parameter is passed to `virtualenv` on creation of the virtual environment, so that +all needed files are copied into it instead of symlinked. ### `virtualenvs.options.no-pip` -**Type**: boolean +**Type**: `boolean` -If set to `true` the `--no-pip` parameter is passed to `virtualenv` on creation of the venv. This means when a new -virtual environment is created, `pip` will not be installed in the environment. -Defaults to `false`. +**Default**: `false` + +*Introduced in 1.2.0* + +If set to `true` the `--no-pip` parameter is passed to `virtualenv` on creation of the virtual environment. This means +when a new virtual environment is created, `pip` will not be installed in the environment. {{% note %}} Poetry, for its internal operations, uses the `pip` wheel embedded in the `virtualenv` package installed as a dependency @@ -306,12 +328,15 @@ packages. This is desirable for production environments. ### `virtualenvs.options.no-setuptools` -**Type**: boolean +**Type**: `boolean` -If set to `true` the `--no-setuptools` parameter is passed to `virtualenv` on creation of the venv. This means when a new -virtual environment is created, `setuptools` will not be installed in the environment. Poetry, for its internal operations, -does not require `setuptools` and this can safely be set to `true`. -Defaults to `false`. +**Default**: `false` + +*Introduced in 1.2.0* + +If set to `true` the `--no-setuptools` parameter is passed to `virtualenv` on creation of the virtual environment. This +means when a new virtual environment is created, `setuptools` will not be installed in the environment. Poetry, for its +internal operations, does not require `setuptools` and this can safely be set to `true`. {{% warning %}} Some development tools like IDEs, make an assumption that `setuptools` (and other) packages are always present and @@ -320,28 +345,33 @@ available within a virtual environment. This can cause some features in these to ### `virtualenvs.options.system-site-packages` -**Type**: boolean +**Type**: `boolean` + +**Default**: `false` Give the virtual environment access to the system site-packages directory. Applies on virtualenv creation. -Defaults to `false`. ### `virtualenvs.prefer-active-python` (experimental) -**Type**: boolean +**Type**: `boolean` + +**Default**: `false` + +*Introduced in 1.2.0* -Use currently activated Python version to create a new venv. -Defaults to `false`, which means Python version used during Poetry installation is used. +Use currently activated Python version to create a new virtual environment. +If set to `false`, Python version used during Poetry installation is used. ### `repositories.` -**Type**: string +**Type**: `string` Set a new alternative repository. See [Repositories]({{< relref "repositories" >}}) for more information. ### `http-basic.`: -**Types**: string, string +**Type**: `(string, string)` Set repository credentials (`username` and `password`) for ``. See [Repositories - Configuring credentials]({{< relref "repositories#configuring-credentials" >}}) @@ -349,7 +379,7 @@ for more information. ### `pypi-token.`: -**Type**: string +**Type**: `string` Set repository credentials (using an API token) for ``. See [Repositories - Configuring credentials]({{< relref "repositories#configuring-credentials" >}}) @@ -357,7 +387,7 @@ for more information. ### `certificates..cert`: -**Type**: string | bool +**Type**: `string | boolean` Set custom certificate authority for repository ``. See [Repositories - Configuring credentials - Custom certificate authority]({{< relref "repositories#custom-certificate-authority-and-mutual-tls-authentication" >}}) @@ -368,7 +398,7 @@ repository. ### `certificates..client-cert`: -**Type**: string +**Type**: `string` Set client certificate for repository ``. See [Repositories - Configuring credentials - Custom certificate authority]({{< relref "repositories#custom-certificate-authority-and-mutual-tls-authentication" >}}) From 025bd9b846ba9435416578e7abdb8df801bf1301 Mon Sep 17 00:00:00 2001 From: Mathieu Kniewallner Date: Sat, 27 Aug 2022 23:40:05 +0200 Subject: [PATCH 2/2] doc(configuration): a-z sort options --- docs/configuration.md | 57 +++++++++++++++++++++---------------------- 1 file changed, 28 insertions(+), 29 deletions(-) diff --git a/docs/configuration.md b/docs/configuration.md index ef74f3456af..9b601677d73 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -171,16 +171,6 @@ Poetry uses `dulwich` by default for git related tasks to not rely on the availa If you encounter any problems with it, set to `true` to use the system git backend. -### `installer.parallel` - -**Type**: `boolean` - -**Default**: `true` - -*Introduced in 1.1.4* - -Use parallel execution when using the new (`>=1.1.0`) installer. - ### `installer.max-workers` **Type**: `int` @@ -249,6 +239,15 @@ Unless this is required system-wide, if configured globally, you could encounter across all your projects if incorrectly set. {{% /warning %}} +### `installer.parallel` + +**Type**: `boolean` + +**Default**: `true` + +*Introduced in 1.1.4* + +Use parallel execution when using the new (`>=1.1.0`) installer. ### `virtualenvs.create` @@ -276,25 +275,6 @@ If set to `true`, the virtualenv will be created and expected in a folder named If set to `false`, `poetry` will ignore any existing `.venv` directory. -### `virtualenvs.path` - -**Type**: `string` - -**Default**: `{cache-dir}/virtualenvs` - -Directory where virtual environments will be created. - -### `virtualenvs.prompt` - -**Type**: `string` - -**Default**: `{project_name}-py{python_version}` - -*Introduced in 1.2.0* - -Format string defining the prompt to be displayed when the virtual environment is activated. -The variables `project_name` and `python_version` are available for formatting. - ### `virtualenvs.options.always-copy` **Type**: `boolean` @@ -352,6 +332,14 @@ available within a virtual environment. This can cause some features in these to Give the virtual environment access to the system site-packages directory. Applies on virtualenv creation. +### `virtualenvs.path` + +**Type**: `string` + +**Default**: `{cache-dir}/virtualenvs` + +Directory where virtual environments will be created. + ### `virtualenvs.prefer-active-python` (experimental) **Type**: `boolean` @@ -363,6 +351,17 @@ Applies on virtualenv creation. Use currently activated Python version to create a new virtual environment. If set to `false`, Python version used during Poetry installation is used. +### `virtualenvs.prompt` + +**Type**: `string` + +**Default**: `{project_name}-py{python_version}` + +*Introduced in 1.2.0* + +Format string defining the prompt to be displayed when the virtual environment is activated. +The variables `project_name` and `python_version` are available for formatting. + ### `repositories.` **Type**: `string`