Skip to content

Commit

Permalink
Reorganize documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@sdispater
sdispater committed Jun 5, 2021
1 parent 7a0fdf9 commit 6a20f7d
Show file tree
Hide file tree
Showing 17 changed files with 594 additions and 312 deletions.
96 changes: 53 additions & 43 deletions docs/docs/index.md → docs/_index.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,17 @@
---
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.


Expand All @@ -9,10 +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
Expand All @@ -30,10 +41,10 @@ curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poet
(Invoke-WebRequest -Uri https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py -UseBasicParsing).Content | python -
```

!!! note

You only need to install Poetry once. It will automatically pick up the current
Python version and use it to [create virtualenvs](/docs/managing-environments) accordingly.
{{% note %}}
You only need to install Poetry once. It will automatically pick up the current
Python version and use it to [create virtualenvs]({{< relref "managing-environments" >}}) accordingly.
{{% /note %}}

The installer installs the `poetry` tool to Poetry's `bin` directory.
On Unix it is located at `$HOME/.poetry/bin` and on Windows at `%USERPROFILE%\.poetry\bin`.
Expand Down Expand Up @@ -81,29 +92,29 @@ python get-poetry.py --version 0.12.0
POETRY_VERSION=0.12.0 python get-poetry.py
```

!!!note
{{% note %}}
Note that the installer does not support Poetry releases < 0.12.0.
{{% /note %}}

Note that the installer does not support Poetry releases < 0.12.0.
{{% note %}}
The setup script must be able to find one of following executables in your shell's path environment:

!!!note

The setup script must be able to find one of following executables in your shell's path environment:

- `python` (which can be a py3 or py2 interpreter)
- `python3`
- `py.exe -3` (Windows)
- `py.exe -2` (Windows)
- `python` (which can be a py3 or py2 interpreter)
- `python3`
- `py.exe -3` (Windows)
- `py.exe -2` (Windows)
{{% /note %}}

### Alternative installation methods (not recommended)

!!!note

Using alternative installation methods will make Poetry always
use the Python version for which it has been installed to create
virtualenvs.
{{% note %}}
Using alternative installation methods will make Poetry always
use the Python version for which it has been installed to create
virtualenvs.

So, you will need to install Poetry for each Python version you
want to use and switch between them.
So, you will need to install Poetry for each Python version you
want to use and switch between them.
{{% /note %}}

#### Installing with `pip`

Expand All @@ -113,14 +124,14 @@ 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 %}}

#### Installing with `pipx`

Using [`pipx`](https://github.com/cs01/pipx) to install Poetry is also possible. [pipx] is used to install Python CLI applications globally while still isolating them in virtual environments. This allows for clean upgrades and uninstalls. pipx supports Python 3.6 and later. If using an earlier version of Python, consider [pipsi](https://github.com/mitsuhiko/pipsi).
Using [`pipx`](https://github.com/cs01/pipx) to install Poetry is also possible. `pipx` is used to install Python CLI applications globally while still isolating them in virtual environments. This allows for clean upgrades and uninstalls. pipx supports Python 3.6 and later. If using an earlier version of Python, consider [pipsi](https://github.com/mitsuhiko/pipsi).

```bash
pipx install poetry
Expand Down Expand Up @@ -158,15 +169,14 @@ to `self update`.
poetry self update 0.8.0
```

!!!note

The `self update` command will only work if you used the recommended
installer to install Poetry.

!!!note

If you are still on poetry version < 1.0 use `poetry self:update` instead.
{{% note %}}
The `self update` command will only work if you used the recommended
installer to install Poetry.
{{% /note %}}

{{% note %}}
If you are still on poetry version < 1.0 use `poetry self:update` instead.
{{% /note %}}

## Enable tab completion for Bash, Fish, or Zsh

Expand Down Expand Up @@ -199,9 +209,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`:

Expand All @@ -211,7 +221,7 @@ fpath+=~/.zfunc

For `oh-my-zsh`, you must then enable poetry in your `~/.zshrc` plugins

```
```text
plugins(
poetry
...
Expand Down
73 changes: 42 additions & 31 deletions docs/docs/basic-usage.md → docs/basic-usage.md
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,18 @@
---
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 "." >}} "Introduction") chapter.

## Project setup

Expand Down Expand Up @@ -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" >}} "virtualenv.in-project configuration documentation") configuration variable
to create virtual environment within your project directory.


Expand All @@ -96,19 +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

**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.
{{% note %}}
**Why a new shell?**

Therefore, Poetry has to create a sub-shell with the virtual envrionment activated
in order for the subsequent commands to run from within the virtual environment.
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 envrionment 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
virtual environment by running `source {path_to_venv}/bin/activate` (`source {path_to_venv}\Scripts\activate.bat` on Windows).
Expand All @@ -128,21 +139,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
{{% note %}}
**How does Poetry download the right files?**

**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
Expand Down Expand Up @@ -189,9 +200,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

Expand All @@ -212,7 +223,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 %}}
38 changes: 24 additions & 14 deletions docs/docs/cli.md → docs/cli.md
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,14 @@
---
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.
Expand Down Expand Up @@ -116,7 +127,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"
Expand All @@ -132,7 +143,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.
Expand Down Expand Up @@ -237,10 +247,10 @@ If you want the dependency to be installed in editable mode you can specify it i
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:
Expand Down Expand Up @@ -355,7 +365,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

Expand Down Expand Up @@ -419,9 +429,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
Expand Down Expand Up @@ -466,9 +476,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

Expand All @@ -486,7 +496,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

Expand Down
Loading

0 comments on commit 6a20f7d

Please sign in to comment.