Skip to content

P
python-poetry
Commit 0d2d3dd0 by Sébastien Eustace Committed by GitHub
Options

Merge pull request #4142 from python-poetry/reorganize-docs 

Reorganize documentation
parents 6bd4f1a6 bce4ac5d
Showing with 387 additions and 370 deletions
.github/workflows/docs.yml deleted 100644 → 0
name: Documentation
on:
push:
paths:
- 'docs/**'
- '.github/workflows/docs.yml'
branches:
- master
pull_request:
paths:
- 'docs/**'
- '.github/workflows/docs.yml'
branches:
- '**'
jobs:
docs:
name: Documentation Build
runs-on: Ubuntu-latest
steps:
- uses: actions/checkout@v2
- uses: actions/setup-python@v2
with:
python-version: 3.8
- name: Install tox
run: pip install tox
- name: Build documentation
run: tox -e doc
docs/docs/index.md → docs/_index.md
---
title: "Introduction"
draft: false
type: docs
layout: "single"
menu:
docs:
weight: 0
---
# Introduction
Poetry is a tool for dependency management and packaging in Python.
Poetry is a tool for **dependency management** and **packaging** in Python.
It allows you to declare the libraries your project depends on and it will manage (install/update) them for you.
......@@ -9,11 +20,10 @@ It allows you to declare the libraries your project depends on and it will manag
Poetry requires Python 2.7 or 3.5+. It is multi-platform and the goal is to make it work equally well
on Windows, Linux and OSX.
!!! note
Python 2.7 and 3.5 will no longer be supported in the next feature release (1.2).
You should consider updating your Python version to a supported one.
{{% note %}}
Python 2.7 and 3.5 will no longer be supported in the next feature release (1.2).
You should consider updating your Python version to a supported one.
{{% /note %}}
## Installation
......@@ -29,10 +39,10 @@ curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/install-
(Invoke-WebRequest -Uri https://raw.githubusercontent.com/python-poetry/poetry/master/install-poetry.py -UseBasicParsing).Content | python -
```
!!!warning
The previous `get-poetry.py` installer is now deprecated, if you are currently using it
you should migrate to the new, supported, `install-poetry.py` installer.
{{% warning %}}
The previous `get-poetry.py` installer is now deprecated, if you are currently using it
you should migrate to the new, supported, `install-poetry.py` installer.
{{% /warning %}}
The installer installs the `poetry` tool to Poetry's `bin` directory. This location depends on your system:
......@@ -89,9 +99,9 @@ You can also install Poetry for a `git` repository by using the `--git` option:
python install-poetry.py --git https://github.com/python-poetry/poetry.git@master
````
!!!note
Note that the installer does not support Python < 3.6.
{{% note %}}
Note that the installer does not support Python < 3.6.
{{% /note %}}
### Alternative installation methods
......@@ -123,25 +133,24 @@ Using `pip` to install Poetry is possible.
pip install --user poetry
```
!!!warning
Be aware that it will also install Poetry's dependencies
which might cause conflicts with other packages.
{{% warning %}}
Be aware that it will also install Poetry's dependencies
which might cause conflicts with other packages.
{{% /warning %}}
## Updating `poetry`
Updating Poetry to the latest stable version is as simple as calling the `self update` command.
!!!warning
Poetry versions installed using the now deprecated `get-poetry.py` installer will not be able to use this
command to update to 1.2 releases or later. Migrate to using the `install-poetry.py` installer or `pipx`.
```bash
poetry self update
```
{{% warning %}}
Poetry versions installed using the now deprecated `get-poetry.py` installer will not be able to use this
command to update to 1.2 releases or later. Migrate to using the `install-poetry.py` installer or `pipx`.
{{% /warning %}}
If you want to install pre-release versions, you can use the `--preview` option.
```bash
......@@ -187,9 +196,9 @@ poetry completions zsh > ~/.zprezto/modules/completion/external/src/_poetry
```
!!! note
You may need to restart your shell in order for the changes to take effect.
{{% note %}}
You may need to restart your shell in order for the changes to take effect.
{{% /note %}}
For `zsh`, you must then add the following line in your `~/.zshrc` before `compinit`:
......@@ -199,7 +208,7 @@ fpath+=~/.zfunc
For `oh-my-zsh`, you must then enable poetry in your `~/.zshrc` plugins
```
```text
plugins(
poetry
...
......
docs/docs/basic-usage.md → docs/basic-usage.md
---
title: "Basic usage"
draft: false
type: docs
layout: single
menu:
docs:
weight: 10
---
# Basic usage
For the basic usage introduction we will be installing `pendulum`, a datetime library.
If you have not yet installed Poetry, refer to the [Introduction](/docs/) chapter.
If you have not yet installed Poetry, refer to the [Introduction]({{< relref "docs" >}} "Introduction") chapter.
## Project setup
......@@ -77,8 +88,8 @@ It will automatically find a suitable version constraint **and install** the pac
## Using your virtual environment
By default, poetry creates a virtual environment in `{cache-dir}/virtualenvs` (`{cache-dir}\virtualenvs` on Windows).
You can change the [`cache-dir`](/docs/configuration/#cache-dir) value by editing the poetry config.
Additionally, you can use the [`virtualenvs.in-project`](/docs/configuration/#virtualenvs.in-project) configuration variable
You can change the [`cache-dir`]({{< relref "configuration#cache-dir" >}} "cache-dir configuration documentation") value by editing the poetry config.
Additionally, you can use the [`virtualenvs.in-project`]({{< relref "configuration#virtualenvsin-project" >}} "#virtualenvs.in-project configuration documentation") configuration variable
to create virtual environment within your project directory.
......@@ -96,18 +107,19 @@ The easiest way to activate the virtual environment is to create a new shell wit
To deactivate the virtual environment and exit this new shell type `exit`.
To deactivate the virtual environment without leaving the shell use `deactivate`.
!!!note
{{% note %}}
**Why a new shell?**
**Why a new shell?**
Child processes inherit their environment from their parents, but do not share
them. As such, any modifications made by a child process, is not persisted after
the child process exits. A Python application (Poetry), being a child process,
cannot modify the environment of the shell that it has been called from such
that an activated virtual environment remains active after the Poetry command
has completed execution.
Child processes inherit their environment from their parents, but do not share
them. As such, any modifications made by a child process, is not persisted after
the child process exits. A Python application (Poetry), being a child process,
cannot modify the environment of the shell that it has been called from such
that an activated virtual environment remains active after the Poetry command
has completed execution.
Therefore, Poetry has to create a sub-shell with the virtual environment activated
in order for the subsequent commands to run from within the virtual environment.
Therefore, Poetry has to create a sub-shell with the virtual environment activated
in order for the subsequent commands to run from within the virtual environment.
{{% /note %}}
Alternatively, to avoid creating a new shell, you can manually activate the
......@@ -116,11 +128,11 @@ To get the path to your virtual environment run `poetry env info --path`.
You can also combine these into a nice one-liner, `source $(poetry env info --path)/bin/activate`
To deactivate this virtual environment simply use `deactivate`.
| | POSIX Shell | Windows | Exit/Deactivate |
|-------------------|---------------------------------------------------|---------------------------------------------|-----------------|
| New Shell | `poetry shell` | `poetry shell` | `exit` |
| Manual Activation | `source {path_to_venv}/bin/activate` | `{path_to_venv}\Scripts\activate.bat` | `deactivate` |
| One-liner | ```source `poetry env info --path`/bin/activate```| | `deactivate` |
| | POSIX Shell | Windows | Exit/Deactivate |
| ----------------- | -------------------------------------------------- | ------------------------------------- | --------------- |
| New Shell | `poetry shell` | `poetry shell` | `exit` |
| Manual Activation | `source {path_to_venv}/bin/activate` | `{path_to_venv}\Scripts\activate.bat` | `deactivate` |
| One-liner | ```source `poetry env info --path`/bin/activate``` | | `deactivate` |
### Version constraints
......@@ -128,21 +140,21 @@ To deactivate this virtual environment simply use `deactivate`.
In our example, we are requesting the `pendulum` package with the version constraint `^1.4`.
This means any version greater or equal to 1.4.0 and less than 2.0.0 (`>=1.4.0 <2.0.0`).
Please read [Dependency specification](/docs/dependency-specification) for more in-depth information on versions,
Please read [Dependency specification]({{< relref "dependency-specification" >}} "Dependency specification documentation") for more in-depth information on versions,
how versions relate to each other, and on the different ways you can specify dependencies.
!!!note
**How does Poetry download the right files?**
{{% note %}}
**How does Poetry download the right files?**
When you specify a dependency in `pyproject.toml`, Poetry first takes the name of the package
that you have requested and searches for it in any repository you have registered using the `repositories` key.
If you have not registered any extra repositories, or it does not find a package with that name in the
repositories you have specified, it falls back on PyPI.
When you specify a dependency in `pyproject.toml`, Poetry first takes the name of the package
that you have requested and searches for it in any repository you have registered using the `repositories` key.
If you have not registered any extra repositories, or it does not find a package with that name in the
repositories you have specified, it falls back on PyPI.
When Poetry finds the right package, it then attempts to find the best match
for the version constraint you have specified.
When Poetry finds the right package, it then attempts to find the best match
for the version constraint you have specified.
{{% /note %}}
## Installing dependencies
......@@ -189,9 +201,9 @@ Even if you develop alone, in six months when reinstalling the project you can f
the dependencies installed are still working even if your dependencies released many new versions since then.
(See note below about using the update command.)
!!!note
For libraries it is not necessary to commit the lock file.
{{% note %}}
For libraries it is not necessary to commit the lock file.
{{% /note %}}
### Installing dependencies only
......@@ -212,7 +224,7 @@ This will fetch the latest matching versions (according to your `pyproject.toml`
and update the lock file with the new versions.
(This is equivalent to deleting the `poetry.lock` file and running `install` again.)
!!!note
Poetry will display a **Warning** when executing an install command if `poetry.lock` and `pyproject.toml`
are not synchronized.
{{% note %}}
Poetry will display a **Warning** when executing an install command if `poetry.lock` and `pyproject.toml`
are not synchronized.
{{% /note %}}
docs/docs/cli.md → docs/cli.md
---
title: "Commands"
draft: false
type: docs
layout: single
menu:
docs:
weight: 30
---
# Commands
You've already learned how to use the command-line interface to do some things.
......@@ -143,7 +155,7 @@ poetry install --remove-untracked
```
You can also specify the extras you want installed
by passing the `-E|--extras` option (See [Extras](/docs/pyproject/#extras) for more info)
by passing the `-E|--extras` option (See [Extras]({{< relref "pyproject#extras" >}}) for more info)
```bash
poetry install --extras "mysql pgsql"
......@@ -159,7 +171,6 @@ Installing dependencies from lock file
No dependencies to install or update
- Installing <your-package-name> (x.x.x)
```
If you want to skip this installation, use the `--no-root` option.
......@@ -286,10 +297,10 @@ Alternatively, you can specify it in the `pyproject.toml` file. It means that ch
my-package = {path = "../my/path", develop = true}
```
!!!note
Before poetry 1.1 path dependencies were installed in editable mode by default. You should always set the `develop` attribute explicit,
to make sure the behavior is the same for all poetry versions.
{{% note %}}
Before poetry 1.1 path dependencies were installed in editable mode by default. You should always set the `develop` attribute explicit,
to make sure the behavior is the same for all poetry versions.
{{% /note %}}
If the package(s) you want to install provide extras, you can specify them
when adding the package:
......@@ -409,7 +420,7 @@ poetry config [options] [setting-key] [setting-value1] ... [setting-valueN]
````
`setting-key` is a configuration option name and `setting-value1` is a configuration value.
See [Configuration](/docs/configuration/) for all available settings.
See [Configuration]({{< relref "configuration" >}}) for all available settings.
### Options
......@@ -473,9 +484,9 @@ poetry search requests pendulum
This command locks (without installing) the dependencies specified in `pyproject.toml`.
!!!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.
{{% 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.
{{% /note %}}
```bash
poetry lock
......@@ -497,17 +508,17 @@ The new version should ideally be a valid [semver](https://semver.org/) string o
The table below illustrates the effect of these rules with concrete examples.
| rule | before | after |
|------------|---------------|---------------|
| major | 1.3.0 | 2.0.0 |
| minor | 2.1.4 | 2.2.0 |
| patch | 4.1.1 | 4.1.2 |
| premajor | 1.0.2 | 2.0.0-alpha.0 |
| preminor | 1.0.2 | 1.1.0-alpha.0 |
| prepatch | 1.0.2 | 1.0.3-alpha.0 |
| prerelease | 1.0.2 | 1.0.3-alpha.0 |
| rule | before | after |
| ---------- | ------------- | ------------- |
| major | 1.3.0 | 2.0.0 |
| minor | 2.1.4 | 2.2.0 |
| patch | 4.1.1 | 4.1.2 |
| premajor | 1.0.2 | 2.0.0-alpha.0 |
| preminor | 1.0.2 | 1.1.0-alpha.0 |
| prepatch | 1.0.2 | 1.0.3-alpha.0 |
| prerelease | 1.0.2 | 1.0.3-alpha.0 |
| prerelease | 1.0.3-alpha.0 | 1.0.3-alpha.1 |
| prerelease | 1.0.3-beta.0 | 1.0.3-beta.1 |
| prerelease | 1.0.3-beta.0 | 1.0.3-beta.1 |
### Options
......@@ -521,9 +532,9 @@ This command exports the lock file to other formats.
poetry export -f requirements.txt --output requirements.txt
```
!!!note
Only the `requirements.txt` format is currently supported.
{{% note %}}
Only the `requirements.txt` format is currently supported.
{{% /note %}}
### Options
......@@ -541,7 +552,7 @@ poetry export -f requirements.txt --output requirements.txt
The `env` command regroups sub commands to interact with the virtualenvs
associated with a specific project.
See [Managing environments](/docs/managing-environments/) for more information about these commands.
See [Managing environments]({{< relref "managing-environments" >}}) for more information about these commands.
## cache
......@@ -628,18 +639,18 @@ For example, to add the `pypi-test` source, you can run:
poetry source add pypi-test https://test.pypi.org/simple/
```
!!!note
You cannot use the name `pypi` as it is reserved for use by the default PyPI source.
{{% note %}}
You cannot use the name `pypi` as it is reserved for use by the default PyPI source.
{{% /note %}}
#### Options
* `--default`: Set this source as the [default](/docs/repositories/#disabling-the-pypi-repository) (disable PyPI).
* `--secondary`: Set this source as a [secondary](/docs/repositories/#install-dependencies-from-a-private-repository) source.
* `--default`: Set this source as the [default]({{< relref "repositories#disabling-the-pypi-repository" >}}) (disable PyPI).
* `--secondary`: Set this source as a [secondary]({{< relref "repositories#install-dependencies-from-a-private-repository" >}}) source.
!!!note
You cannot set a source as both `default` and `secondary`.
{{% note %}}
You cannot set a source as both `default` and `secondary`.
{{% /note %}}
### `source show`
......@@ -655,9 +666,9 @@ Optionally, you can show information of one or more sources by specifying their
poetry source show pypi-test
```
!!!note
This command will only show sources configured via the `pyproject.toml` and does not include PyPI.
{{% note %}}
This command will only show sources configured via the `pyproject.toml` and does not include PyPI.
{{% /note %}}
### `source remove`
......
docs/docs/configuration.md → docs/configuration.md
---
title: "Configuration"
draft: false
type: docs
layout: single
menu:
docs:
weight: 40
---
# Configuration
Poetry can be configured via the `config` command ([see more about its usage here](/docs/cli/#config))
Poetry can be configured via the `config` command ([see more about its usage here]({{< relref "docs/cli#config" >}} "config command documentation"))
or directly in the `config.toml` file that will be automatically be created when you first run that command.
This file can typically be found in one of the following directories:
......@@ -93,7 +104,9 @@ export POETRY_HTTP_BASIC_MY_REPOSITORY_PASSWORD=secret
## Available settings
### `cache-dir`: string
### `cache-dir`
**Type**: string
The path to the cache directory used by Poetry.
......@@ -103,28 +116,35 @@ Defaults to one of the following directories:
- Windows: `C:\Users\<username>\AppData\Local\pypoetry\Cache`
- Unix: `~/.cache/pypoetry`
### `installer.parallel`: boolean
### `installer.parallel`
**Type**: boolean
Use parallel execution when using the new (`>=1.1.0`) installer.
Defaults to `true`.
!!!note:
This configuration will be ignored, and parallel execution disabled when running
Python 2.7 under Windows.
{{% note %}}
This configuration will be ignored, and parallel execution disabled when running
Python 2.7 under Windows.
{{% /note %}}
### `virtualenvs.create`
### `virtualenvs.create`: boolean
**Type**: boolean
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.
!!!note
{{% note %}}
When setting this configuration to `false`, the Python environment used must have `pip`
installed and available.
{{% /note %}}
When setting this configuration to `false`, the Python environment used must have `pip`
installed and available.
### `virtualenvs.in-project`
### `virtualenvs.in-project`: boolean
**Type**: boolean
Create the virtualenv inside the project's root directory.
Defaults to `None`.
......@@ -136,22 +156,30 @@ If not set explicitly (default), `poetry` will use the virtualenv from the `.ven
directory when one is available. If set to `false`, `poetry` will ignore any
existing `.venv` directory.
### `virtualenvs.path`: string
### `virtualenvs.path`
**Type**: string
Directory where virtual environments will be created.
Defaults to `{cache-dir}/virtualenvs` (`{cache-dir}\virtualenvs` on Windows).
### `virtualenvs.options.always-copy`: boolean
### `virtualenvs.options.always-copy`
**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`.
### `virtualenvs.options.system-site-packages`: boolean
### `virtualenvs.options.system-site-packages`
**Type**: boolean
Give the virtual environment access to the system site-packages directory.
Applies on virtualenv creation.
Defaults to `false`.
### `repositories.<name>`: string
### `repositories.<name>`
**Type**: string
Set a new alternative repository. See [Repositories](/docs/repositories/) for more information.
Set a new alternative repository. See [Repositories]({{< relref "repositories" >}}) for more information.
docs/docs/dependency-specification.md → docs/dependency-specification.md
---
title: "Dependency specification"
draft: false
type: docs
layout: single
menu:
docs:
weight: 70
---
# Dependency specification
Dependencies for a project can be specified in various forms, which depend on the type
......@@ -119,10 +130,10 @@ my-package = { path = "../my-package/", develop = false }
my-package = { path = "../my-package/dist/my-package-0.1.0.tar.gz" }
```
!!!note
Before poetry 1.1 directory path dependencies were installed in editable mode by default. You should set the `develop` attribute explicitly,
to make sure the behavior is the same for all poetry versions.
{{% note %}}
Before poetry 1.1 directory path dependencies were installed in editable mode by default. You should set the `develop` attribute explicitly,
to make sure the behavior is the same for all poetry versions.
{{% /note %}}
## `url` dependencies
......@@ -185,10 +196,10 @@ foo = [
]
```
!!!note
The constraints **must** have different requirements (like `python`)
otherwise it will cause an error when resolving dependencies.
{{% note %}}
The constraints **must** have different requirements (like `python`)
otherwise it will cause an error when resolving dependencies.
{{% /note %}}
## Expanded dependency specification syntax
......
docs/docs/faq.md → docs/faq.md
---
title: "FAQ"
draft: false
type: docs
layout: single
menu:
docs:
weight: 110
---
# FAQ
## Why is the dependency resolution process slow?
### Why is the dependency resolution process slow?
While the dependency resolver at the heart of Poetry is highly optimized and
should be fast enough for most cases, sometimes, with some specific set of dependencies,
......@@ -13,18 +24,18 @@ operation, both in bandwidth and time, which is why it seems this is a long proc
At the moment there is no way around it.
!!!note
Once Poetry has cached the releases' information, the dependency resolution process
will be much faster.
{{% note %}}
Once Poetry has cached the releases' information, the dependency resolution process
will be much faster.
{{% /note %}}
## Why are unbound version constraints a bad idea?
### Why are unbound version constraints a bad idea?
A version constraint without an upper bound such as `*` or `>=3.4` will allow updates to any future version of the dependency.
This includes major versions breaking backward compatibility.
Once a release of your package is published, you cannot tweak its dependencies anymore in case a dependency breaks BC
- you have to do a new release but the previous one stays broken.
– you have to do a new release but the previous one stays broken.
The only good alternative is to define an upper bound on your constraints,
which you can increase in a new release after testing that your package is compatible
......@@ -33,9 +44,9 @@ with the new major version of your dependency.
For example instead of using `>=3.4` you should use `~3.4` which allows all versions `<4.0`.
The `^` operator works very well with libraries following [semantic versioning](https://semver.org).
## Is tox supported?
### Is tox supported?
Yes. By using the [isolated builds](https://tox.readthedocs.io/en/latest/config.html#conf-isolated_build) `tox` provides,
**Yes**. By using the [isolated builds](https://tox.readthedocs.io/en/latest/config.html#conf-isolated_build) `tox` provides,
you can use it in combination with the PEP 517 compliant build system provided by Poetry.
So, in your `pyproject.toml` file, add this section if it does not already exist:
......@@ -60,7 +71,7 @@ commands =
poetry run pytest tests/
```
## I don't want Poetry to manage my virtual environments. Can I disable it?
### I don't want Poetry to manage my virtual environments. Can I disable it?
While Poetry automatically creates virtual environments to always work isolated
from the global Python installation, there are valid reasons why it's not necessary
......
docs/docs/libraries.md → docs/libraries.md
---
title: "Libraries"
draft: false
type: docs
layout: "docs"
menu:
docs:
weight: 20
---
# Libraries
This chapter will tell you how to make your library installable through Poetry.
......@@ -9,7 +21,7 @@ While Poetry does not enforce any convention regarding package versioning,
it **strongly** recommends to follow [semantic versioning](https://semver.org).
This has many advantages for the end users and allows them to set appropriate
[version constraints](/docs/dependency-specification/#version-constraints).
[version constraints]({{< relref "dependency-specification#version-constraints" >}}).
## Lock file
......@@ -49,14 +61,14 @@ poetry publish
```
This will package and publish the library to PyPI, at the condition that you are a registered user
and you have [configured your credentials](/docs/repositories/#adding-credentials) properly.
!!!note
and you have [configured your credentials]({{< relref "repositories#configuring-credentials" >}}) properly.
The `publish` command does not execute `build` by default.
{{% note %}}
The `publish` command does not execute `build` by default.
If you want to build and publish your packages together,
just pass the `--build` option.
If you want to build and publish your packages together,
just pass the `--build` option.
{{% /note %}}
Once this is done, your library will be available to anyone.
......@@ -68,7 +80,7 @@ Sometimes, you may want to keep your library private but also being accessible t
In this case, you will need to use a private repository.
In order to publish to a private repository, you will need to add it to your
global list of repositories. See [Adding a repository](/docs/repositories/#adding-a-repository)
global list of repositories. See [Adding a repository]({{< relref "repositories#adding-a-repository" >}})
for more information.
Once this is done, you can actually publish to it like so:
......
docs/docs/managing-environments.md → docs/managing-environments.md
---
title: "Managing environments"
draft: false
type: docs
layout: "docs"
menu:
docs:
weight: 60
---
# Managing environments
Poetry makes project environment isolation one of its core features.
......@@ -15,19 +26,19 @@ 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 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.
{{% 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 is Python 2.7 only, a standard workflow
would be:
For instance, if your project is Python 2.7 only, a standard workflow
would be:
```bash
pyenv install 2.7.15
pyenv local 2.7.15 # Activate Python 2.7 for the current project
poetry install
```
```bash
pyenv install 2.7.15
pyenv local 2.7.15 # Activate Python 2.7 for the current project
poetry install
```
{{% /note %}}
## Switching between environments
......
docs/mkdocs.yml deleted 100644 → 0
site_name: Poetry documentation
theme:
name: null
custom_dir: theme
extra:
version: 2.0
nav:
- Introduction: index.md
- Basic Usage: basic-usage.md
- Libraries: libraries.md
- Commands: cli.md
- Configuration: configuration.md
- Repositories: repositories.md
- Managing environments: managing-environments.md
- Dependency specification: dependency-specification.md
- Plugins: plugins.md
- The pyproject.toml file: pyproject.md
- Contributing: contributing.md
- FAQ: faq.md
markdown_extensions:
- codehilite
- admonition
- pymdownx.superfences
- toc:
permalink:
- markdown_include.include:
base_path: docs
docs/docs/plugins.md → docs/plugins.md
---
title: "Plugins"
draft: false
type: docs
layout: single
menu:
docs:
weight: 80
---
# Plugins
Poetry supports using and building plugins if you wish to
......@@ -18,7 +29,7 @@ and may also depend on further packages.
### Plugin package
The plugin package must depend on Poetry
and declare a proper [plugin](/docs/pyproject/#plugins) in the `pyproject.toml` file.
and declare a proper [plugin]({{< relref "pyproject#plugins" >}}) in the `pyproject.toml` file.
```toml
[tool.poetry]
......@@ -96,19 +107,19 @@ class MyApplicationPlugin(ApplicationPlugin):
application.command_loader.register_factory("my-command", factory)
```
!!!note
It's possible to do the following to register the command:
{{% note %}}
It's possible to do the following to register the command:
```python
application.add(MyCommand())
```
```python
application.add(MyCommand())
```
However, it is **strongly** recommended to register a new factory
in the command loader to defer the loading of the command when it's actually
called.
However, it is **strongly** recommended to register a new factory
in the command loader to defer the loading of the command when it's actually
called.
This will help keep the performances of Poetry good.
This will help keep the performances of Poetry good.
{{% /note %}}
The plugin also must be declared in the `pyproject.toml` file of the plugin package
as an `application.plugin` plugin:
......@@ -118,9 +129,9 @@ as an `application.plugin` plugin:
foo-command = "poetry_demo_plugin.plugin:MyApplicationPlugin"
```
!!!warning
A plugin **must not** remove or modify in any way the core commands of Poetry.
{{% warning %}}
A plugin **must not** remove or modify in any way the core commands of Poetry.
{{% /warning %}}
### Event handler
......@@ -152,10 +163,15 @@ from poetry.plugins.application_plugin import ApplicationPlugin
class MyApplicationPlugin(ApplicationPlugin):
def activate(self, application: Application):
application.event_dispatcher.add_listener(COMMAND, self.load_dotenv)
application.event_dispatcher.add_listener(
COMMAND, self.load_dotenv
)
def load_dotenv(
self, event: ConsoleCommandEvent, event_name: str, dispatcher: EventDispatcher
self,
event: ConsoleCommandEvent,
event_name: str,
dispatcher: EventDispatcher
) -> None:
command = event.command
if not isinstance(command, EnvCommand):
......@@ -164,7 +180,9 @@ class MyApplicationPlugin(ApplicationPlugin):
io = event.io
if io.is_debug():
io.write_line("<debug>Loading environment variables.</debug>")
io.write_line(
"<debug>Loading environment variables.</debug>"
)
load_dotenv()
```
......@@ -188,7 +206,7 @@ The `plugin add` command will ensure that the plugin is compatible with the curr
and install the needed packages for the plugin to work.
The package specification formats supported by the `plugin add` command are the same as the ones supported
by the [`add` command](/docs/cli/#add).
by the [`add` command]({{< relref "cli#add" >}}).
If you no longer need a plugin and want to uninstall it, you can use the `plugin remove` command.
......
docs/docs/pyproject.md → docs/pyproject.md
---
title: "The pyproject.toml file"
draft: false
type: docs
layout: single
menu:
docs:
weight: 90
---
# The `pyproject.toml` file
The `tool.poetry` section of the `pyproject.toml` file is composed of multiple sections.
......@@ -40,9 +51,9 @@ The recommended notation for the most common licenses is (alphabetical):
Optional, but it is highly recommended to supply this.
More identifiers are listed at the [SPDX Open Source License Registry](https://spdx.org/licenses/).
!!!note
If your project is proprietary and does not use a specific licence, you can set this value as `Proprietary`.
{{% note %}}
If your project is proprietary and does not use a specific licence, you can set this value as `Proprietary`.
{{% /note %}}
## authors
......@@ -91,11 +102,11 @@ classifiers = [
]
```
!!!note
{{% note %}}
Note that Python classifiers are still automatically added for you and are determined by your `python` requirement.
Note that Python classifiers are still automatically added for you and are determined by your `python` requirement.
The `license` property will also set the License classifier automatically.
The `license` property will also set the License classifier automatically.
{{% /note %}}
## packages
......@@ -137,26 +148,26 @@ packages = [
From now on, only the `sdist` build archive will include the `my_other_package` package.
!!!note
Using `packages` disables the package auto-detection feature meaning you have to
**explicitly** specify the "default" package.
{{% note %}}
Using `packages` disables the package auto-detection feature meaning you have to
**explicitly** specify the "default" package.
For instance, if you have a package named `my_package` and you want to also include
another package named `extra_package`, you will need to specify `my_package` explicitly:
For instance, if you have a package named `my_package` and you want to also include
another package named `extra_package`, you will need to specify `my_package` explicitly:
```toml
packages = [
{ include = "my_package" },
{ include = "extra_package" },
]
```
!!!note
```toml
packages = [
{ include = "my_package" },
{ include = "extra_package" },
]
```
{{% /note %}}
Poetry is clever enough to detect Python subpackages.
{{% note %}}
Poetry is clever enough to detect Python subpackages.
Thus, you only have to specify the directory where your root package resides.
Thus, you only have to specify the directory where your root package resides.
{{% /note %}}
## include and exclude
......@@ -208,15 +219,15 @@ name = 'private'
url = 'http://example.com/simple'
```
!!!note
Be aware that declaring the python version for which your package
is compatible is mandatory:
{{% note %}}
Be aware that declaring the python version for which your package
is compatible is mandatory:
```toml
[tool.poetry.dependencies]
python = "^3.6"
```
```toml
[tool.poetry.dependencies]
python = "^3.6"
```
{{% /note %}}
## `scripts`
......@@ -229,9 +240,9 @@ poetry = 'poetry.console:run'
Here, we will have the `poetry` script installed which will execute `console.run` in the `poetry` package.
!!!note
When a script is added or updated, run `poetry install` to make them available in the project's virtualenv.
{{% note %}}
When a script is added or updated, run `poetry install` to make them available in the project's virtualenv.
{{% /note %}}
## `extras`
......@@ -276,10 +287,11 @@ the `databases` extra can be installed as shown below.
pip install awesome[databases]
```
!!!note
{{% note %}}
The dependencies specified for each `extra` must already be defined as project dependencies.
The dependencies specified for each `extra` must already be defined as project dependencies.
Dependencies listed in the `dev-dependencies` section cannot be specified as extras.
Dependencies listed in the `dev-dependencies` section cannot be specified as extras.
{{% /note %}}
## `plugins`
......@@ -322,12 +334,11 @@ requires = ["poetry-core>=1.0.0"]
build-backend = "poetry.core.masonry.api"
```
!!!note
When using the `new` or `init` command this section will be automatically added.
!!!note
{{% note %}}
When using the `new` or `init` command this section will be automatically added.
{{% /note %}}
If your `pyproject.toml` file still references `poetry` directly as a build backend,
you should update it to reference `poetry-core` instead.
{{% note %}}
If your `pyproject.toml` file still references `poetry` directly as a build backend,
you should update it to reference `poetry-core` instead.
{{% /note %}}
docs/docs/repositories.md → docs/repositories.md
---
title: "Repositories"
draft: false
type: docs
layout: "docs"
menu:
docs:
weight: 50
---
# Repositories
## Using the PyPI repository
......@@ -37,24 +48,25 @@ poetry config http-basic.foo username password
If you do not specify the password you will be prompted to write it.
!!!note
{{% note %}}
To publish to PyPI, you can set your credentials for the repository named `pypi`.
To publish to PyPI, you can set your credentials for the repository named `pypi`.
Note that it is recommended to use [API tokens](https://pypi.org/help/#apitoken)
when uploading packages to PyPI.
Once you have created a new token, you can tell Poetry to use it:
Note that it is recommended to use [API tokens](https://pypi.org/help/#apitoken)
when uploading packages to PyPI.
Once you have created a new token, you can tell Poetry to use it:
```bash
poetry config pypi-token.pypi my-token
```
```bash
poetry config pypi-token.pypi my-token
```
If you still want to use your username and password, you can do so with the following
call to `config`.
If you still want to use your username and password, you can do so with the following
call to `config`.
```bash
poetry config http-basic.pypi username password
```
{{% /note %}}
```bash
poetry config http-basic.pypi username password
```
You can also specify the username and password when using the `publish` command
with the `--username` and `--password` options.
......@@ -71,7 +83,7 @@ export POETRY_HTTP_BASIC_PYPI_USERNAME=username
export POETRY_HTTP_BASIC_PYPI_PASSWORD=password
```
See [Using environment variables](/docs/configuration/#using-environment-variables) for more information
See [Using environment variables]({{< relref "configuration#using-environment-variables" >}}) for more information
on how to configure Poetry with environment variables.
#### Custom certificate authority and mutual TLS authentication
......@@ -79,9 +91,10 @@ Poetry supports repositories that are secured by a custom certificate authority
certificate-based client authentication. The following will configure the "foo" repository to validate the repository's
certificate using a custom certificate authority and use a client certificate (note that these config variables do not
both need to be set):
```bash
poetry config certificates.foo.cert /path/to/ca.pem
poetry config certificates.foo.client-cert /path/to/client.pem
poetry config certificates.foo.cert /path/to/ca.pem
poetry config certificates.foo.client-cert /path/to/client.pem
```
### Install dependencies from a private repository
......@@ -99,19 +112,19 @@ url = "https://foo.bar/simple/"
From now on, Poetry will also look for packages in your private repository.
!!!note
{{% note %}}
Any custom repository will have precedence over PyPI.
Any custom repository will have precedence over PyPI.
If you still want PyPI to be your primary source for your packages
you can declare custom repositories as secondary.
If you still want PyPI to be your primary source for your packages
you can declare custom repositories as secondary.
```toml
[[tool.poetry.source]]
name = "foo"
url = "https://foo.bar/simple/"
secondary = true
```
```toml
[[tool.poetry.source]]
name = "foo"
url = "https://foo.bar/simple/"
secondary = true
```
{{% /note %}}
If your private repository requires HTTP Basic Auth be sure to add the username and
password to your `http-basic` configuration using the example above (be sure to use the
......
docs/theme/main.html deleted 100644 → 0
---
layout: documentation
title: {{ page.title|striptags|e }}
---
<section class="p-b-50 p-t-50 documentation-content">
<div class="container">
<div class="panel panel-transparent">
<div class="row p-l-20 p-r-20 p-b-20 p-t-5 xs-no-padding">
<div class="row">
<div class="col-md-3 documentation-toc">
<ul class="current">
{% set navlevel = 1 %}
{% for nav_item in nav %}
<li class="toctree-l{{ navlevel }}{% if nav_item.active and not nav_item.children %} current{%endif%}">
{% include 'nav.html' %}
</li>
{% endfor %}
</ul>
</div>
<div class="col-md-9 documentation-body">
{{page.content}}
</div>
</div>
</div>
</div>
</div>
</section>
docs/theme/nav.html deleted 100644 → 0
<a class="{% if nav_item.active%}current{%endif%}" href="{{ base_url }}/{{ nav_item.url }}">{{ nav_item.title }}</a>
{%- if nav_item == page or nav_item.children %}
<ul class="subnav">
{%- if nav_item == page %}
{% include 'toc.html' %}
{%- endif %}
{%- if nav_item.children %}
{%- set navlevel = navlevel + 1%}
{%- for nav_item in nav_item.children %}
<li class="{% if navlevel > 2 %}toctree-l{{ navlevel }}{% endif %}{% if nav_item.active%} current{%endif%}">
{% include 'nav.html' %}
</li>
{%- endfor %}
{%- set navlevel = navlevel - 1%}
{%- endif %}
</ul>
{%- endif %}
docs/theme/toc.html deleted 100644 → 0
{% for toc_item in page.toc %}
<!--<li class="toctree-l{{ navlevel + 1 }}"><a href="{{ toc_item.url }}">{{ toc_item.title }}</a></li>-->
{% if toc_item.children %}
<ul>
{% for toc_item in toc_item.children %}
<li><a class="toctree-l{{ navlevel + 2 }}" href="{{ toc_item.url }}">{{ toc_item.title }}</a></li>
{% endfor %}
</ul>
{% endif %}
{% endfor %}
tox.ini
......@@ -8,15 +8,3 @@ whitelist_externals = poetry
commands =
poetry install -vv --no-root
poetry run pytest {posargs} tests/
[testenv:doc]
whitelist_externals =
skip_install = true
deps =
markdown-include
mkdocs
pygments
pygments-github-lexers
pymdown-extensions
commands =
mkdocs build -f docs/mkdocs.yml
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment