Skip to content

Commit

Permalink
Merge pull request #4145 from python-poetry/1.1-reorganize-docs
Browse files Browse the repository at this point in the history 
[1.1] Reorganize documentation
  • Loading branch information
@sdispater
sdispater committed Jun 5, 2021
2 parents 7a0fdf9 + d14b131 commit 67c1b34
Show file tree
Hide file tree
Showing 18 changed files with 594 additions and 341 deletions.
29 changes: 0 additions & 29 deletions .github/workflows/docs.yml
View file

This file was deleted.

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 %}}

0 comments on commit 67c1b34

Please sign in to comment.