From 707b6e0ca7c95bbd71c8730d18967ca2d80d5f6c Mon Sep 17 00:00:00 2001
From: Ivan Habunek <ivan@habunek.com>
Date: Tue, 1 Oct 2024 08:36:51 +0200
Subject: [PATCH] Update installation instructions

---
 docs/installation.md | 53 ++++++++++++++++++++++++++++++++++++++------
 1 file changed, 46 insertions(+), 7 deletions(-)

diff --git a/docs/installation.md b/docs/installation.md
index 02ef65ed..14c2d3be 100644
--- a/docs/installation.md
+++ b/docs/installation.md
@@ -1,22 +1,61 @@
 Installation
 ============
 
+## Package repositories
+
 toot is packaged for various platforms. If possible use your OS's package manager to install toot.
 
-[![Packaging status](https://repology.org/badge/vertical-allrepos/toot.svg)](https://repology.org/project/toot/versions)
+<details>
+    <summary>Packaging status</summary>
+    <a href="https://repology.org/project/toot/versions" style="display: block; margin-top: 2rem">
+        <img src="https://repology.org/badge/vertical-allrepos/toot.svg" alt="Packaging status" />
+    </a>
+</details>
 
-## Python Package Index
+## Homebrew
 
-Install from PyPI using pip, preferably into a virtual environment.
+For Mac users, toot is available [in homebrew](https://formulae.brew.sh/formula/toot#default).
 
-    pip install toot
+    brew install toot
 
-## Homebrew
+## Using pipx
 
-For Mac OSX users, toot is available [in homebrew](https://formulae.brew.sh/formula/toot#default).
+pipx installs packages from PyPI into isolated environments. It is the
+recommended installation method if there is no OS package or the package is
+outdated.
 
-    brew install toot
+Firstly, install pipx following their [installation instructions](https://pipx.pypa.io/stable/installation/).
+
+Install toot:
+
+    pipx install toot
+
+Install with optional image support:
+
+    pipx install "toot[images]"
+
+Upgrade to latest version:
+
+    pipx upgrade toot
 
 ## From source
 
 You can get the latest source distribution [from Github](https://github.com/ihabunek/toot/releases/latest/).
+
+Clone the project and install into a virtual environment.
+
+```
+git clone git@github.com:ihabunek/toot.git
+cd toot
+python3 -m venv .venv
+source .venv/bin/activate
+pip install .
+```
+
+After this, the executable is available at `.venv/bin/toot`.
+
+To install with optonal image support:
+
+```
+pip install ".[images]"
+```
\ No newline at end of file