docs: rework installation and update docs

Also tweak the plugin docs to match

Co-authored-by: Bjorn Neergaard <[email protected]>

Author: Secrus

docs/_index.md

@@ -13,6 +13,7 @@ menu:
 
 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.
+Poetry offers a lockfile to ensure repeatable installs, and can build your project for distribution.
 
 
 ## System requirements
@@ -22,27 +23,43 @@ on Linux, macOS and Windows.
 
 ## Installation
 
-{{< tabs tabTotal="3" tabID1="installing-with-the-official-installer" tabID2="installing-with-pipx" tabID3="installing-with-pip" tabName1="With the official installer" tabName2="With pipx" tabName3="With pip" >}}
+{{% note %}}
+If you are viewing documentation for the development branch, you may wish to install a preview or development version of Poetry.
+See the **advanced** installation instructions to use a preview or alternate version of Poetry.
+{{% /note %}}
+
+{{< tabs tabTotal="3" tabID1="installing-with-the-official-installer" tabID2="installing-with-pipx" tabID3="installing-manually" tabName1="With the official installer" tabName2="With pipx" tabName3="Manually (advanced)" >}}
 
 {{< tab tabID="installing-with-the-official-installer" >}}
 
-Poetry provides a custom installer that will install `poetry` isolated
-from the rest of your system.
+We provide a custom installer that will install Poetry in a new virtual environment to isolate it
+from the rest of your system. This ensures that dependencies will not be accidentally upgraded or
+uninstalled, and allows Poetry to manage its own environment.
 
 {{< steps >}}
 {{< step >}}
 **Install Poetry**
 
-Install Poetry by downloading and executing the [installation script](https://install.python-poetry.org).
+The installer script is available directly at [install.python-poetry.org](https://install.python-poetry.org),
+and is developed in [its own repository](https://github.com/python-poetry/install.python-poetry.org).
+The script can be executed directly (i.e. 'curl python') or downloaded and then executed from disk
+(e.g. in a CI environment).
+
+{{% warning %}}
+The previous `get-poetry.py` and `install-poetry.py` installers are deprecated. Any installs performed
+using `get-poetry.py` should be uninstalled and reinstalled using `install.python-poetry.org` to ensure
+in-place upgrades are possible.
+{{% /warning %}}
 
 **Linux, macOS, Windows (WSL)**
 
 ```bash
 curl -sSL https://install.python-poetry.org | python3 -
 ```
+
 {{% note %}}
-Note: On some systems, `python` may still refer to Python 2 instead of Python 3. Please always use the
-`python3` binary to ensure the right major version of Python is used.
+Note: On some systems, `python` may still refer to Python 2 instead of Python 3. We always suggest the
+`python3` binary to avoid ambiguity.
 {{% /note %}}
 
 **Windows (Powershell)**
@@ -55,60 +72,31 @@ If you have installed Python through the Microsoft Store, replace `py` with `pyt
 above.
 {{% /note %}}
 
-{{% note %}}
-Note that the installer does not support Python < 3.7.
-{{% /note %}}
-
-{{% warning %}}
-The previous `get-poetry.py` and `install-poetry.py` installers are now deprecated. If you are currently using them
-you should migrate to the new, supported, installer through `https://install.python-poetry.org`.
-{{% /warning %}}
 {{< /step >}}
 {{< step >}}
-**Add Poetry to your PATH**
-
-The installer installs the `poetry` tool to Poetry's `bin` directory. This location depends on your system:
-
-- `$HOME/.local/bin` for Unix
-- `%APPDATA%\Python\Scripts` on Windows
+**Install Poetry (advanced)**
 
-If this directory is not on your `PATH`, you will need to add it manually
-if you want to invoke Poetry with simply `poetry`.
+By default, Poetry is installed into a platform and user-specific directory:
 
-Alternatively, you can use the full path to `poetry` to use it.
-{{< /step >}}
-
-{{< step >}}
-**Check the installation**
+- `~/Library/Application Support/pypoetry` on MacOS.
+- `~/.local/share/pypoetry` on Linux/Unix.
+- `%APPDATA%\pypoetry` on Windows.
 
-Once Poetry is installed you can execute the following:
-
-```bash
-poetry --version
-```
-
-If you see something like `Poetry (version 1.2.0)` then you are ready to use Poetry.
-{{< /step >}}
-
-{{< step >}}
-**Configure the installation**
-
-By default, Poetry is installed into the user's platform-specific home directory.
-If you wish to change this, you may define the `POETRY_HOME` environment variable:
+If you wish to change this, you may define the `$POETRY_HOME` environment variable:
 
 ```bash
 curl -sSL https://install.python-poetry.org | POETRY_HOME=/etc/poetry python3 -
 ```
 
 If you want to install prerelease versions, you can do so by passing `--preview` option to `install-poetry.py`
-or by using the `POETRY_PREVIEW` environment variable:
+or by using the `$POETRY_PREVIEW` environment variable:
 
 ```bash
 curl -sSL https://install.python-poetry.org | python3 - --preview
 curl -sSL https://install.python-poetry.org | POETRY_PREVIEW=1 python3 -
 ```
 
-Similarly, if you want to install a specific version, you can use `--version` option or the `POETRY_VERSION`
+Similarly, if you want to install a specific version, you can use `--version` option or the `$POETRY_VERSION`
 environment variable:
 
 ```bash
@@ -122,10 +110,45 @@ You can also install Poetry from a `git` repository by using the `--git` option:
 curl -sSL https://install.python-poetry.org | python3 - --git https://github.com/python-poetry/poetry.git@master
 ````
 {{< /step >}}
+{{< step >}}
+**Add Poetry to your PATH**
+
+The installer creates a `poetry` wrapper in a well-known, platform-specific directory:
+
+- `$HOME/.local/bin` on Unix.
+- `%APPDATA%\Python\Scripts` on Windows.
+
+If this directory is not present in your `$PATH`, you can add it in order to invoke Poetry
+as `poetry`.
+
+Alternatively, the full path to the `poetry` binary can always be used:
+
+- `$POETRY_HOME/bin/poetry` if `$POETRY_HOME` is set.
+- `~/Library/Application Support/pypoetry/bin/poetry` on MacOS.
+- `~/.local/share/pypoetry/bin/poetry` on Linux/Unix.
+- `%APPDATA%\pypoetry\Scripts\poetry` on Windows.
+
+{{< /step >}}
+{{< step >}}
+**Use Poetry**
+
+Once Poetry is installed and in your `$PATH`, you can execute the following:
+
+```bash
+poetry --version
+```
 
+If you see something like `Poetry (version 1.2.0)`, your install is ready to use!
+{{< /step >}}
 {{< step >}}
 **Update Poetry**
 
+Poetry is able to update itself when installed using the official installer.
+
+```bash
+poetry self update
+```
+
 If you want to install pre-release versions, you can use the `--preview` option.
 
 ```bash
@@ -140,11 +163,11 @@ poetry self update 1.2.0
 ```
 
 {{% warning %}}
-Poetry versions installed using the deprecated `get-poetry.py` installer will not be able to use this
-command to update to 1.2 releases or later. Migrate to using `https://install.python-poetry.org` or `pipx`.
+Poetry `1.1` series releases are not able to update in-place to `1.2` or newer series releases.
+To migrate to newer releases, uninstall using your original install method, and then reinstall
+using the [methods above]({{< ref "#installation" >}} "Installation").
 {{% /warning %}}
 {{< /step >}}
-
 {{< step >}}
 **Uninstall Poetry**
 
@@ -156,25 +179,61 @@ the `POETRY_UNINSTALL` environment variable before executing the installer.
 curl -sSL https://install.python-poetry.org | python3 - --uninstall
 curl -sSL https://install.python-poetry.org | POETRY_UNINSTALL=1 python3 -
 ```
-{{< /step >}}
 
+{{% warning %}}
+If you installed using the deprecated `get-poetry.py` script, you should use it to uninstall instead:
+
+```bash
+curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | python3 - --uninstall
+```
+{{% /warning %}}
+
+{{< /step >}}
 {{< /steps >}}
 
 {{< /tab >}}
-
 {{< tab tabID="installing-with-pipx" >}}
 
-Using [`pipx`](https://github.com/pypa/pipx) to install Poetry is also possible.
+Using [`pipx`](https://github.com/pypa/pipx) to install Poetry is also possible and fully supported.
 
 `pipx` is used to install Python CLI applications globally while still isolating them in virtual environments.
-This allows for clean upgrades and uninstalls.
+`pipx` will manage upgrades and uninstalls when used to install Poetry.
 
 {{< steps >}}
 {{< step >}}
 **Install Poetry**
 
 ```bash
 pipx install poetry
+```
+{{< /step >}}
+{{< step >}}
+**Install Poetry (advanced)**
+
+`pipx` can be install different versions of Poetry, using the same syntax as pip:
+
+```bash
+pipx install poetry==1.2.0
+```
+
+`pipx` can also install versions of Poetry in parallel, which allows for easy testing of different or prerelease
+versions. Each version is given a unique, user-specified suffix, which will be used to create a unique binary name:
+
+```bash
+pipx install --suffix=@preview --pip-args=--pre poetry
+poetry@preview --version
+
+pipx install [email protected] poetry==1.2.0
+[email protected] --version
+```
+
+Finally, `pipx` can install any valid Python URL spec, which allows for installations of the development version from `git`,
+or even the local testing of Pull Requests:
+
+```
+pipx install --suffix @master git+https://github.com/python-poetry/poetry.git@master
+pipx install --suffix @pr1234 git+https://github.com/python-poetry/poetry.git@refs/pull/1234/head
+
 ```
 {{< /step >}}
 {{< step >}}
@@ -194,22 +253,27 @@ pipx uninstall poetry
 {{< /steps >}}
 
 {{< /tab >}}
+{{< tab tabID="installing-manually" >}}
 
-{{< tab tabID="installing-with-pip" >}}
+Poetry can be installed manually using `pip` and the `venv` module. By doing so you will essentially perform the steps carried
+out by the official installer. As this is an advanced installation method, these instructions are Unix-only and omit specific
+examples such as installing from `git`.
 
-Using `pip` to install Poetry is possible.
+The variable `$VENV_PATH` will be used to indicate the path at which the virtual environment was created.
 
 ```bash
-pip install --user poetry
+python3 -m venv $VENV_PATH
+$VENV_PATH/bin/pip install -U pip setuptools
+$VENV_PATH/bin/pip install poetry
 ```
 
-{{% warning %}}
-Be aware that it will also install Poetry's dependencies
-which might cause conflicts with other packages.
-{{% /warning %}}
+Poetry will be available at `$VENV_PATH/bin/poetry` and can be invoked directly or symlinked elsewhere.
 
-{{< /tab >}}
+As this install is effectively managed by Poetry, `poetry self` commands will still be able to manipulate it.
 
+To uninstall Poetry, simply delete the entire `$VENV_PATH` directory.
+
+{{< /tab >}}
 {{< /tabs >}}
 
 

docs/plugins.md

@@ -233,14 +233,19 @@ pipx runpip poetry uninstall poetry-plugin
 
 ### With `pip`
 
-If you used `pip` to install Poetry you can add the plugin packages via the `pip install` command.
+The `pip` binary in Poetry's virtual environment can also be used to install and remove plugins.
+The environment variable `$POETRY_HOME` here is used to represent the path to the virtual environment.
+The [installation instructions](/docs/) can be referenced if you are not
+sure where Poetry has been installed.
+
+To add a plugin, you can use `pip install`:
 
 ```shell
-pip install --user poetry-plugin
+$POETRY_HOME/bin/pip install --user poetry-plugin
 ```
 
 If you want to uninstall a plugin, you can run:
 
 ```shell
-pip uninstall poetry-plugin
+$POETRY_HOME/bin/pip uninstall poetry-plugin
 ```