README: move sections around and add installation from source instruc…

…tions

This is intended to get new users up to speed quicker.
For them knowing how the USB-SD-Mux works internally is certainly
interesting (at least to me it is),
but having a quick start guide on how to install the software
and use it is even more important.

This also re-structures the quickstart section so that the installation
from different sources is part of it in the form of sub-sections.
This integrates the "Distribution Packages" section better.

I was also a bit confused that none of the installation methods cloned
the git repository, so I've added one.

The "Troubleshooting" section was moved to the bottom of the page,
because that is where I would expect it to be.

Signed-off-by: Leonard Göhrs <l.goehrs@pengutronix.de>

README.rst

@@ -14,38 +14,42 @@ The USB-SD-Mux is built around a `Microchip USB2642 <http://www.microchip.com/ww
 
 This software is aimed to be used with `Labgrid <https://github.com/labgrid-project/labgrid>`_. But it can also be used stand-alone or in your own applications.
 
-High-Level Functions
---------------------
-The ``usbsdmux`` package provides the the following features:
 
-* Muxing the SD-Card to either the DUT, Host or disconnecting it altogether via the ``usbsdmux`` command.
-* Writing the Configuration-EEPROM of the USB2642 from the command line to customize the representation of the USB device via the ``usbsdmux-configure`` command.
+Quickstart
+----------
 
-Low-Level Functions
--------------------
-Under the hood this tool provides interfaces to access the following features of the Microchip USB2642:
+To get started with the ``usbsdmux`` tool you will first need to install the ``usbsdmux`` package.
+There are different methods to doing this:
 
-* Accessing the auxiliary I2C bus with write and write-read transactions with up to 512 bytes of payload using a simple Python interface.
-* Writing an I2C Configuration-EEPROM on the configuration I2C.
-  This is done using an undocumented command that was reverse-engineered from Microchip's freely available EOL-Tools.
+Installation from your Linux Distribution
+  The easiest way to install the ``usbsdmux`` tool and stay somewhat up to date without having to deal with Python virtual environments.
+  May not be available for your distribution and may be lacking in features because distributions ship older software versions.
 
-Packages
---------
+Installation from PyPi
+  Another way to install the ``usbsdmux`` from a pre-packaged source.
+  Always installs the latest ``usbsdmux`` release, but needs to be kept up to date manually.
+  Also needs a re-install when your systems Python version is updated.
 
-.. image:: https://repology.org/badge/vertical-allrepos/usbsdmux.svg
-   :target: https://repology.org/project/usbsdmux/versions
-   :alt: Packaging status
-   :align: right
+Installation from Source
+  The way to go if you can not wait to test out new features.
+
+Installation from Distribution Packages
+```````````````````````````````````````
 
 This tool is `packaged <https://packages.debian.org/search?keywords=usbsdmux&searchon=names&exact=1>`_ in Debian 12
 (aka *bookworm*) and later.
 The package ships the ``usbsdmux`` tool and the corresponding *udev* -rules.
 So you can simply ``apt install usbsdmux`` and skip all installation steps below.
 
+.. image:: https://repology.org/badge/vertical-allrepos/usbsdmux.svg
+   :target: https://repology.org/project/usbsdmux/versions
+   :alt: Packaging status
+   :align: right
+
 Packages also exist for `some other distributions <https://repology.org/project/usbsdmux/versions>`_.
 
-Quickstart
-----------
+Installation from PyPi Packages
+```````````````````````````````
 
 Create and activate a Python virtual environment for the ``usbsdmux`` package:
 
@@ -60,7 +64,24 @@ Install the ``usbsdmux`` package into the virtual environment:
 
    $ python3 -m pip install usbsdmux
 
-Now you can run ``usbsdmux`` command with the ``-h`` flag to get a list of possible
+Installation From Source
+````````````````````````
+
+To get the latest and greatest you can also install the ``usbsdmux`` package
+right from the git repository:
+
+.. code-block:: bash
+
+   $ git clone https://github.com/linux-automation/usbsdmux.git
+   $ cd usbsdmux
+   $ python3 -m venv venv
+   $ source venv/bin/activate
+   $ python3 -m pip install .
+
+Usage
+`````
+
+Once installed you can run ``usbsdmux`` command with the ``-h`` flag to get a list of possible
 command invocations:
 
 .. code-block:: text
@@ -86,6 +107,7 @@ command invocations:
      --config CONFIG       Set config file location
      --json                Format output as json. Useful for scripting.
 
+
 Using as root
 -------------
 If you just want to try the USB-SD-Mux (or maybe if it is just ok for you) you
@@ -99,6 +121,7 @@ shell-wrapper along with the appropriate `/dev/sg*` device path:
    $ sudo /path/to/venv/bin/usbsdmux /dev/sg0 dut
    $ sudo /path/to/venv/bin/usbsdmux /dev/sg0 host
 
+
 Using as normal user / Reliable names
 -------------------------------------
 
@@ -140,6 +163,35 @@ the ``/dev/usb-sd-mux/`` directory:
        Depending on your Linux distribution you may want to create/use another
        group for this purpose and adapt the ``udev`` rule accordingly.
 
+
+How it works
+------------
+
+High-Level Functions
+````````````````````
+The ``usbsdmux`` package provides the the following features:
+
+* Muxing the SD-Card to either the DUT, Host or disconnecting it altogether via the ``usbsdmux`` command.
+* Writing the Configuration-EEPROM of the USB2642 from the command line to customize the representation of the USB device via the ``usbsdmux-configure`` command.
+
+Low-Level Functions
+```````````````````
+Under the hood this tool provides interfaces to access the following features of the Microchip USB2642:
+
+* Accessing the auxiliary I2C bus with write and write-read transactions with up to 512 bytes of payload using a simple Python interface.
+* Writing an I2C Configuration-EEPROM on the configuration I2C.
+  This is done using an undocumented command that was reverse-engineered from Microchip's freely available EOL-Tools.
+
+
+MQTT Statistics
+---------------
+
+This tool can be configured to send certain statistics to a MQTT broker.
+To enable this function create a config file at ``/etc/usbsdmux.config`` or use ``--config`` specify a file location.
+
+See example config file `usbsdmux.config <contrib/usbsdmux.config>`_.
+
+
 Troubleshooting
 ---------------
 
@@ -164,13 +216,6 @@ Troubleshooting
     :alt: pypi.org
     :target: https://pypi.org/project/usbsdmux
 
-MQTT Statistics
----------------
-
-This tool can be configured to send certain statistics to a MQTT broker.
-To enable this function create a config file at ``/etc/usbsdmux.config`` or use ``--config`` specify a file location.
-
-See example config file `usbsdmux.config <contrib/usbsdmux.config>`_.
 
 Contributing
 ------------