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 <[email protected]>
python-poetry · May 23, 2022 · 3349ba9 · 3349ba9
1 parent 8a2eceb
commit 3349ba9
Show file tree

Hide file tree

Showing 7 changed files with 68 additions and 12 deletions.
diff --git a/docs/basic-usage.md b/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`.
 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
 

diff --git a/docs/cli.md b/docs/cli.md
@@ -297,6 +297,10 @@ present dependency you can use the special `latest` constraint:
 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:
 
 ```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.
 
 {{% 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 %}}
 
 ```bash
@@ -587,7 +591,7 @@ This command locks (without installing) the dependencies specified in `pyproject
 
 {{% 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.
-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 %}}
 
 ```bash
@@ -645,7 +649,7 @@ poetry export -f requirements.txt --output requirements.txt
 
 {{% note %}}
 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 %}}

diff --git a/docs/configuration.md b/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.
 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
 `.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`
 
@@ -295,3 +296,35 @@ Defaults to `false`, which means Python version used during Poetry installation
 **Type**: string
 
 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.
diff --git a/docs/dependency-specification.md b/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
 ```
 
+## 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
 
-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:
 
 ```toml

diff --git a/docs/faq.md b/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.
-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.
 
 

diff --git a/docs/pre-commit-hooks.md b/docs/pre-commit-hooks.md
@@ -33,7 +33,7 @@ to make sure the poetry configuration does not get committed in a broken state.
 ### Arguments
 
 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
@@ -44,7 +44,7 @@ to make sure the lock file is up-to-date when committing changes.
 ### Arguments
 
 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
@@ -59,7 +59,7 @@ It is recommended to run the [`poetry-lock`](#poetry-lock) hook prior to this on
 ### Arguments
 
 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"]`,
 which will create/update the requirements.txt file in the current working directory.

diff --git a/docs/pyproject.md b/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).
 
+{{% note %}}
+Explicitly declaring entries in `include` will negate VCS' ignore settings.
+{{% /note %}}
+
 ```toml
 [tool.poetry]
 # ...