Changes in docs for Issues #4800, #3709, #3573, #2211 and PR #2414 (#5656)

* Changes in docs for Issues #4800, #3709, #3573, #2211, #521 and PR #2414

- Added section about `extras` in `dependency-specification.md` (#2414)
- Added note about VCS inclusion and exclusion in `include`/`exclude`
sections of `pyproject.toml` (#4800)
- Added link to dependency specification in `add` command documentation
(#3573)
- Added more info on default behaviour and cleaned up
`virtualenv.in-project` setting documentation (#3709)
- Added missing configuration options to `configuration.md` (#2211)

Co-authored-by: Arun Babu Neelicattu <arun.neelicattu@gmail.com>

docs/basic-usage.md

@@ -58,7 +58,7 @@ build-backend = "poetry.core.masonry.api"
 Poetry assumes your package contains a package with the same name as `tool.poetry.name`.
 Poetry assumes your package contains a package with the same name as `tool.poetry.name`.
 If this is not the case, populate `tool.poetry.packages` to specify your package or packages.
 If this is not the case, populate `tool.poetry.packages` to specify your package or packages.
 
 
-See [Packages](/docs/pyproject#packages) for more information.
+See [Packages]({{< relref "pyproject#packages" >}}) for more information.
 
 
 ### Initialising a pre-existing project
 ### Initialising a pre-existing project
 
 

docs/cli.md

@@ -297,6 +297,10 @@ present dependency you can use the special `latest` constraint:
 poetry add pendulum@latest
 poetry add pendulum@latest
 ```
 ```
 
 
+{{% note %}}
+See the [Dependency specification]({{< relref "dependency-specification" >}}) for more information on setting the version constraints for a package.
+{{% /note %}}
+
 You can also add `git` dependencies:
 You can also add `git` dependencies:
 
 
 ```bash
 ```bash
@@ -566,7 +570,7 @@ The `check` command validates the structure of the `pyproject.toml` file
 and returns a detailed report if there are any errors.
 and returns a detailed report if there are any errors.
 
 
 {{% note %}}
 {{% note %}}
-This command is also available as a pre-commit hook. See [pre-commit hooks](/docs/pre-commit-hooks#poetry-check) for more information.
+This command is also available as a pre-commit hook. See [pre-commit hooks]({{< relref "pre-commit-hooks#poetry-check">}}) for more information.
 {{% /note %}}
 {{% /note %}}
 
 
 ```bash
 ```bash
@@ -587,7 +591,7 @@ This command locks (without installing) the dependencies specified in `pyproject
 
 
 {{% note %}}
 {{% note %}}
 By default, this will lock all dependencies to the latest available compatible versions. To only refresh the lock file, use the `--no-update` option.
 By default, this will lock all dependencies to the latest available compatible versions. To only refresh the lock file, use the `--no-update` option.
-This command is also available as a pre-commit hook. See [pre-commit hooks](/docs/pre-commit-hooks#poetry-lock) for more information.
+This command is also available as a pre-commit hook. See [pre-commit hooks]({{< relref "pre-commit-hooks#poetry-lock">}}) for more information.
 {{% /note %}}
 {{% /note %}}
 
 
 ```bash
 ```bash
@@ -645,7 +649,7 @@ poetry export -f requirements.txt --output requirements.txt
 
 
 {{% note %}}
 {{% note %}}
 This command is provided by the [Export Poetry Plugin](https://github.com/python-poetry/poetry-plugin-export)
 This command is provided by the [Export Poetry Plugin](https://github.com/python-poetry/poetry-plugin-export)
-and is also available as a pre-commit hook. See [pre-commit hooks](/docs/pre-commit-hooks#poetry-export) for more information.
+and is also available as a pre-commit hook. See [pre-commit hooks]({{< relref "pre-commit-hooks#poetry-export" >}}) for more information.
 {{% /note %}}
 {{% /note %}}
 
 
 {{% note %}}
 {{% note %}}

docs/configuration.md

@@ -215,12 +215,13 @@ If set to `false`, poetry will install dependencies into the current python envi
 Create the virtualenv inside the project's root directory.
 Create the virtualenv inside the project's root directory.
 Defaults to `None`.
 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.
+
 If set to `true`, the virtualenv will be created and expected in a folder named
 If set to `true`, the virtualenv will be created and expected in a folder named
 `.venv` within the root directory of the project.
 `.venv` within the root directory of the project.
 
 
-If not set explicitly (default), `poetry` will use the virtualenv from the `.venv`
-directory when one is available. If set to `false`, `poetry` will ignore any
-existing `.venv` directory.
+If set to `false`, `poetry` will ignore any existing `.venv` directory.
 
 
 ### `virtualenvs.path`
 ### `virtualenvs.path`
 
 
@@ -295,3 +296,35 @@ Defaults to `false`, which means Python version used during Poetry installation
 **Type**: string
 **Type**: string
 
 
 Set a new alternative repository. See [Repositories]({{< relref "repositories" >}}) for more information.
 Set a new alternative repository. See [Repositories]({{< relref "repositories" >}}) for more information.
+
+### `http-basic.<name>`:
+
+**Types**: string, string
+
+Set repository credentials (`username` and `password`) for `<name>`.
+See [Repositories - Configuring credentials]({{< relref "repositories#configuring-credentials" >}})
+for more information.
+
+### `pypi-token.<name>`:
+
+**Type**: string
+
+Set repository credentials (using an API token) for `<name>`.
+See [Repositories - Configuring credentials]({{< relref "repositories#configuring-credentials" >}})
+for more information.
+
+### `certificates.<name>.cert`:
+
+**Type**: string
+
+Set custom certificate authority for repository `<name>`.
+See [Repositories - Configuring credentials - Custom certificate authority]({{< relref "repositories#custom-certificate-authority-and-mutual-tls-authentication" >}})
+for more information.
+
+### `certificates.<name>.client-cert`:
+
+**Type**: string
+
+Set client certificate for repository `<name>`.
+See [Repositories - Configuring credentials - Custom certificate authority]({{< relref "repositories#custom-certificate-authority-and-mutual-tls-authentication" >}})
+for more information.

docs/dependency-specification.md

@@ -180,9 +180,24 @@ with the corresponding `add` call:
 poetry add https://example.com/my-package-0.1.0.tar.gz
 poetry add https://example.com/my-package-0.1.0.tar.gz
 ```
 ```
 
 
+## Dependency `extras`
+
+You can specify [PEP-508 Extras](https://www.python.org/dev/peps/pep-0508/#extras)
+for a dependency as shown here.
+
+```toml
+[tool.poetry.dependencies]
+gunicorn = { version = "^20.1", extras = ["gevent"] }
+```
+
+{{% note %}}
+These activate extra defined for the dependency, to configure an optional dependency
+for extras in your project refer to [`extras`]({{< relref "pyproject#extras" >}}).
+{{% /note %}}
+
 ## `source` dependencies
 ## `source` dependencies
 
 
-To depend on a package from an [alternate repository](/docs/repositories/#install-dependencies-from-a-private-repository),
+To depend on a package from an [alternate repository]({{< relref "repositories/#install-dependencies-from-a-private-repository" >}}),
 you can use the `source` property:
 you can use the `source` property:
 
 
 ```toml
 ```toml

docs/faq.md

@@ -104,7 +104,7 @@ The current project's Python requirement (>=3.7.0,<4.0.0) is not compatible with
 ```
 ```
 
 
 Usually you will want to match the Python requirement of your project with the upper bound of the failing dependency.
 Usually you will want to match the Python requirement of your project with the upper bound of the failing dependency.
-Alternative you can tell Poetry to install this dependency [only for a specific range of Python versions](/docs/dependency-specification/#multiple-constraints-dependencies),
+Alternative you can tell Poetry to install this dependency [only for a specific range of Python versions]({{< relref "dependency-specification#multiple-constraints-dependencies" >}}),
 if you know that it's not needed in all versions.
 if you know that it's not needed in all versions.
 
 
 
 

docs/pre-commit-hooks.md

@@ -33,7 +33,7 @@ to make sure the poetry configuration does not get committed in a broken state.
 ### Arguments
 ### Arguments
 
 
 The hook takes the same arguments as the poetry command.
 The hook takes the same arguments as the poetry command.
-For more information see the [check command](/docs/cli#check).
+For more information see the [check command]({{< relref "cli#check" >}}).
 
 
 
 
 ## poetry-lock
 ## poetry-lock
@@ -44,7 +44,7 @@ to make sure the lock file is up-to-date when committing changes.
 ### Arguments
 ### Arguments
 
 
 The hook takes the same arguments as the poetry command.
 The hook takes the same arguments as the poetry command.
-For more information see the [lock command](/docs/cli#lock).
+For more information see the [lock command]({{< relref "cli#lock" >}}).
 
 
 
 
 ## poetry-export
 ## poetry-export
@@ -59,7 +59,7 @@ It is recommended to run the [`poetry-lock`](#poetry-lock) hook prior to this on
 ### Arguments
 ### Arguments
 
 
 The hook takes the same arguments as the poetry command.
 The hook takes the same arguments as the poetry command.
-For more information see the [export command](/docs/cli#export).
+For more information see the [export command]({{< relref "cli#export" >}}).
 
 
 The default arguments are `args: ["-f", "requirements.txt", "-o", "requirements.txt"]`,
 The default arguments are `args: ["-f", "requirements.txt", "-o", "requirements.txt"]`,
 which will create/update the requirements.txt file in the current working directory.
 which will create/update the requirements.txt file in the current working directory.

docs/pyproject.md

@@ -235,6 +235,10 @@ The globs specified in the exclude field identify a set of files that are not in
 
 
 If a VCS is being used for a package, the exclude field will be seeded with the VCS’ ignore settings (`.gitignore` for git for example).
 If a VCS is being used for a package, the exclude field will be seeded with the VCS’ ignore settings (`.gitignore` for git for example).
 
 
+{{% note %}}
+Explicitly declaring entries in `include` will negate VCS' ignore settings.
+{{% /note %}}
+
 ```toml
 ```toml
 [tool.poetry]
 [tool.poetry]
 # ...
 # ...