Merge pull request #165 from JOJ0/dev

Rework README install chapter and recommend `pipx`

README.md

@@ -4,8 +4,6 @@
 - [About](#about)
 - [Prerequisites](#prerequisites)
 - [Installation](#installation)
-  - [Install from PyPI](#install-from-pypi)
-  - [Install from git](#install-from-git)
 - [Configuration](#configuration)
   - [Getting an Admin Token](#getting-an-admin-token)
   - [The configurator](#the-configurator)
@@ -21,14 +19,11 @@
 - [Contributing](#contributing)
 
 
-
-
 ## About
 
 A CLI tool to help admins of [Matrix-Synapse homeservers](https://github.com/matrix-org/synapse) conveniently issue commands available via its [Admin API](https://element-hq.github.io/synapse/develop/usage/administration/admin_api/index.html#the-admin-api).
 
 
-
 ## Prerequisites
 
 - Python 3.6+
@@ -39,59 +34,23 @@ A CLI tool to help admins of [Matrix-Synapse homeservers](https://github.com/mat
 `synadm` is designed to run either directly on the host running the Synapse instance or on a remote machine able to access Synapse's API port. Synapse's default Admin API endpoint address usually is http://localhost:8008/_synapse/admin or https://localhost:8448/_synapse/admin.
 
 
-
-
 ## Installation
 
-### Install from PyPI
-
-`pip3 install synadm`
-
-### Install from git
-
-<!-- omit in toc -->
-#### 1. Check Python Version
-
-`python3 --version` should show at least v3.6.x
-
-<!-- omit in toc -->
-#### 2. Clone Repo:
-
-```
-git clone https://github.com/joj0/synadm
-```
-
-<!-- omit in toc -->
-#### 3. Install Package Globally
-
-This will install `synadm` and all dependent Python packages to your system's global Python site-packages directory:
+If `pipx` is available on your operating system, it is the recommended method for installation:
 
-```
-cd synadm
-sudo pip install .
-```
-
-*Note: If you get an import error for setuptools, make sure the package is installed. Debian based systems: `sudo apt install python3-setuptools`, RedHat based: `sudo yum install python3-setuptools`* 
-
-<!-- omit in toc -->
-#### 4. Run
-
-`synadm` should now run fine without having to add a path in front of it:
+`pipx install synadm`
 
-```
-synadm -h
-```
+Alternatively, regular `pip` can also be used:
 
-*Note: Usually setuptools installs a command wrapper to `/usr/local/bin/synadm`, but that depends on your system.*
-
-*Note: In case you don't want `synadm` to be installed to a global system directory, you can find an [alternative way of installing](CONTRIBUTING.md#getting-the-source--installing) in the contribution docs*.
-
-*Note: synadm is multi-user aware - it stores its configuration inside the executing user's home directory. See chapter [configuration](#configuration).*
+`pip3 install synadm`
 
+To install the latest version from Git to a Python virtual environment [see the chapter in the contributing docs](https://synadm.readthedocs.io/en/latest/contributing.html#getting-the-source-and-installing).
 
 
 ## Configuration
 
+`synadm` stores its configuration inside the executing user's home directory in `~/.config/synadm.yaml`) and is handled by [the synadm configurator](#the-configurator). Usually it's not required to edit it manually.
+
 ### Getting an Admin Token
 
 To find out your admin user's token in Element-Web: _Login as this user - "Click User Avatar" - "All Settings" - "Help & About" - Scroll down - "Advanced" - "Access Token"_
@@ -109,6 +68,7 @@ If you issue this command in a fresh `synadm` installation, [the configurator](#
 - Set token to "invalid" at first, to convience `synadm` to launch the `matrix login` command (otherwise you'd get a "Configuration incomplete" error).
 - After successfully entering your admin password you will be presented a token which you can finally set by re-launching the configurator as described below.
 
+
 ### The configurator
 
 `synadm` asks for necessary configuration items on first launch automatically. Also whenever new mandatory configuration items where added (eg after an update), the user will be prompted for missing items automatically.
@@ -121,7 +81,6 @@ synadm config
 
 Configuration will be saved in `~/.config/synadm.yaml`
 
-
 *Note: Be aware that once you configured `synadm`, your admin user's token is saved in the configuration file. On Posix compatible systems permissions are set to mode 0600, on other OS's it is your responsibilty to change permissions accordingly.*
 
 ### matrix-docker-ansible-deploy
@@ -148,6 +107,7 @@ _Note that currently `synadm` is using a part of the Server-Server (Federation)
 
 Find more details about the topic [here](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/1761#issuecomment-1101170229).
 
+
 ## Usage
 
 Use the online help of the main command:
@@ -182,14 +142,14 @@ will show essential help for the particular subcommand right away.
 
 A detailed [Command Line Reference](https://synadm.readthedocs.io/en/latest/index_cli_reference.html) can be found in `synadm's` readthedocs documentation.
 
-
 ### Advanced Usage
 
 Examples of how `synadm` can be used in shell scripts and oneliners is
 provided in the
 [Scripting Examples](https://synadm.readthedocs.io/en/latest/examples.html)
 docs chapter.
 
+
 ## Update
 
 ### Update PyPI Package
@@ -235,4 +195,4 @@ If you are sure you've found a bug that was not already reported, certainly dire
 
 First of all, thanks for your interest in contributing to `synadm`! We appreciate any help, no matter if you are a programmer or a user. Both groups can do valuable things for the `synadm` project. We love providing a useful tool to fellow Synapse sysadmins but rely on contribution from the Synapse and Matrix community to keep `synadm` useful, current and stable.
 
-Please review the [contributing docs](CONTRIBUTING.md) for guidelines and help around the topic!
+Please review the [contributing docs](https://synadm.readthedocs.io/en/latest/contributing.html) for guidelines and help around the topic!