Merge pull request #1160 from Bastian-Krause/bst/readme-improvs

README and documentation improvements

README.rst

@@ -1,18 +1,31 @@
-.. image:: labgrid_logo.png
+.. image:: https://raw.githubusercontent.com/labgrid-project/labgrid/master/labgrid_logo.png
    :alt: labgrid logo
    :align: center
 
 Welcome to labgrid
 ==================
-
 |license| |unit-tests| |docker-build| |coverage-status| |docs-status| |chat| |calver|
 
-Purpose
--------
 Labgrid is an embedded board control python library with a focus on testing, development
 and general automation.
 It includes a remote control layer to control boards connected to other hosts.
 
+* `Purpose and Features <#purpose-and-features>`_
+
+* `Documentation <#documentation>`_
+
+* `Contributing <#contributing>`_
+
+* `Background <#background>`_
+
+* `Installation <#installation>`_
+
+  * `Install Latest Release <#install-latest-release>`_
+
+  * `Install Development State <#install-development-state>`_
+
+Purpose and Features
+--------------------
 The idea behind labgrid is to create an abstraction of the hardware control
 layer needed for testing of embedded systems, automatic software installation
 and automation during development.
@@ -51,26 +64,39 @@ enhancements which are not yet implemented.
 
 Documentation
 -------------
-`Read the Docs <http://labgrid.readthedocs.io/en/latest/>`_
+labgrid's documentation is hosted on `Read the Docs <http://labgrid.readthedocs.io/en/latest/>`_.
 
 Contributing
 ------------
-`Development Docs <http://labgrid.readthedocs.io/en/latest/development.html>`_
+See our `Development Docs <http://labgrid.readthedocs.io/en/latest/development.html>`_.
 
-IRC channel ``#labgrid`` on libera.chat (bridged to the `Matrix channel
-#labgrid:matrix.org <https://app.element.io/#/room/#labgrid:matrix.org>`_)
+Visit us in our IRC channel ``#labgrid`` on libera.chat (bridged to the
+`Matrix channel #labgrid:matrix.org <https://app.element.io/#/room/#labgrid:matrix.org>`_)
 
 Background
 ----------
 Work on labgrid started at `Pengutronix <http://pengutronix.de/>`_ in late 2016
 and is currently in active use and development.
 
-Quickstart
-----------
+Installation
+------------
 See the `Installation section
 <http://labgrid.readthedocs.io/en/latest/getting_started.html#installation>`_
 for more details.
 
+Install Latest Release
+^^^^^^^^^^^^^^^^^^^^^^
+Install labgrid via PyPi:
+
+.. code-block:: bash
+
+   $ virtualenv -p python3 venv
+   $ source venv/bin/activate
+   venv $ pip install --upgrade pip
+   venv $ pip install labgrid
+
+Install Development State
+^^^^^^^^^^^^^^^^^^^^^^^^^
 Clone the git repository:
 
 .. code-block:: bash
@@ -123,6 +149,6 @@ Tests can now run via:
     :alt: chat
     :target: https://app.element.io/#/room/#labgrid:matrix.org
 
-.. |calver| image:: https://img.shields.io/badge/calver-YY.MINOR.%5BMICRO%5D-22bfda.svg
+.. |calver| image:: https://img.shields.io/badge/calver-YY.MINOR%5B.MICRO%5D-22bfda.svg
     :alt: chat
     :target: https://calver.org/

doc/getting_started.rst

@@ -25,6 +25,16 @@ In many cases, the easiest way is to install labgrid into a virtualenv:
     $ source labgrid-venv/bin/activate
     labgrid-venv $ pip install --upgrade pip
 
+Install Latest Release
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: bash
+
+    labgrid-venv $ pip install labgrid
+
+Install Development State
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
 Start by cloning the repository and installing labgrid:
 
 .. code-block:: bash
@@ -37,13 +47,15 @@ Start by cloning the repository and installing labgrid:
    (RFC2217), it is highly recommended to uninstall pyserial after installation
    and replace it with the pyserial version from the labgrid project:
 
-   https://github.com/labgrid-project/pyserial/releases/tag/v3.4.0.1
+   https://github.com/labgrid-project/pyserial/tags
 
    This pyserial version has two fixes for an Issue we found with Serial over IP
    multiplexers. Additionally it reduces the Serial over IP traffic considerably
    since the port is not reconfigured when labgrid changes the timeout (which is
    done inside the library a lot).
 
+Test Installation
+~~~~~~~~~~~~~~~~~
 
 Test your installation by running: