[PATCH 1/2] doc: Split installation and dependencies sections

[Peter Hoyes]

In preparation for expanding the installation section, split
"Dependencies & installation" into separate "Installation" and
"Dependencies" sections.

Installation now comes first, being more relevant for end users.

Signed-off-by: Peter Hoyes <peter...@arm.com>
---
docs/userguide/getting-started.rst | 15 +++++++++------
1 file changed, 9 insertions(+), 6 deletions(-)

diff --git a/docs/userguide/getting-started.rst b/docs/userguide/getting-started.rst
index 9e9b38a..2ae618e 100644
--- a/docs/userguide/getting-started.rst
+++ b/docs/userguide/getting-started.rst
@@ -1,8 +1,15 @@
Getting Started
===============

-Dependencies & installation
----------------------------
+Installation
+------------
+
+To install kas into your python site-package repository, run::
+
+ $ sudo pip3 install .
+
+Dependencies
+------------

This project depends on

@@ -15,10 +22,6 @@ This project depends on
- NEWT Python 3 distro package (optional, for menu plugin)
- python-gnupg Python 3 package (optional, for signature verification)

-To install kas into your python site-package repository, run::
-
- $ sudo pip3 install .
-
Usage
-----

--
2.43.0

[Peter Hoyes]

In 2025, "sudo pip3 install" is no longer a recommended way of installing
non-distro-maintained Python packages and recent Linux distros restrict
installing packages globally using pip. This patch proposes recommending
pipx as the new default installation method.

Rewrite the installation section using pipx. Add a separate sub-section
with details of using kas menu with pipx. Include a section mentioning
the Debian kas package.

Signed-off-by: Peter Hoyes <peter...@arm.com>
---

docs/userguide/getting-started.rst | 27 +++++++++++++++++++++++++--
1 file changed, 25 insertions(+), 2 deletions(-)

diff --git a/docs/userguide/getting-started.rst b/docs/userguide/getting-started.rst
index 2ae618e..fb20af2 100644
--- a/docs/userguide/getting-started.rst
+++ b/docs/userguide/getting-started.rst
@@ -4,9 +4,32 @@ Getting Started
Installation
------------

-To install kas into your python site-package repository, run::

+pipx is the recommended way to install kas. It creates an isolated Python
+virtual environment for kas and makes sure its dependencies are installed
+correctly. To install pipx, follow the instructions at
+https://pipx.pypa.io/stable/installation/

- $ sudo pip3 install .

+To install the latest version of kas using pipx run::
+
+ $ pipx install kas
+
+With menu support
+~~~~~~~~~~~~~~~~~
+
+kas menu requires an additional system dependency. On Debian-based systems,
+run::
+
+ $ sudo apt install python3-newt
+ $ pipx install kas --system-site-packages
+
+Other installation methods
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Debian-based distributions provide a package for kas. However, this may be
+outdated compared to the latest release. To install kas using the system
+package manager, run::
+
+ $ sudo apt install kas

Dependencies
------------
--
2.43.0

[Jan Kiszka]

Thanks, both applied.

Jan

--
Siemens AG, Foundational Technologies
Linux Expert Center