Refactored README, Installation, Contributing

Signed-off-by: Sebastian Schleemilch <[email protected]>

README.md

@@ -1,37 +1,53 @@
 # VSS Tools
 
-
 [![License](https://img.shields.io/badge/License-MPL%202.0-blue.svg)](https://opensource.org/licenses/MPL-2.0)
 [![Build Status](https://github.com/COVESA/vss-tools/actions/workflows/buildcheck.yml/badge.svg)](https://github.com/COVESA/vss-tools/actions/workflows/buildcheck.yml?query=branch%3Amaster)
 
 The overall goal of VSS Tools is to provide a set of tools that can be used to convert or verify Vehicle Signal Specifications defined by the format specified by the [COVESA VSS project](https://github.com/COVESA/vehicle_signal_specification).
 VSS Tools is developed in parallel with VSS, please visit the [COVESA VSS project](https://github.com/COVESA/vehicle_signal_specification) for information on how to contribute.
 If any questions arise, please check out the [FAQ](FAQ.md) for more information.
 
-## Available Tools
+## Installation
 
-This repository contains three categories of tools:
-* Community Supported Tools are tools that are actively maintained by the VSS community.
-  They are run as part of the Continuous Integration process for both this repository and for the [COVESA VSS project repository](https://github.com/COVESA/vehicle_signal_specification),
-  and pull request will normally not be merged if any of the tools fails. That assures that the tools always are compatible with the latest version of the COVESA VSS.
-* Contributed Tools are tools that are not actively maintained by the VSS community.
-  Instead they are maintained by individual contributors, or not maintained at all.
-  Even if many of them are run as part of the continuous integration process,
-  it is not a requirement that they must run successfully on the latest VSS version and a change in VSS may be merged even if it cause some contributed tools to fail.
-* Obsolete Tools are tools that are not maintained and not functional.
+There are several ways of installing `vss-tools`.
+If you would like to contribute then please follow the [contribute](#contributing) section instead.
+All of them are recommended to be done in an activated python virtual environment:
 
-A tool in the Contributed Tools category may be moved to the Obsolete category if it has been non-functional for at least 6 months.
-Tools in the Obsolete Tools category may be deleted after 12 months.
+```bash
+python -m venv .venv
+source .venv/bin/activate
+```
+
+pypi
+```bash
+pip install vss-tools
+```
+
+from source:
+```bash
+# default branch
+pip install git+https://github.com/COVESA/vss-tools.git
+# explicit branch
+pip install git+https://github.com/COVESA/vss-tools.git@master
+# commit
+pip install git+https://github.com/COVESA/vss-tools.git@1234567
+```
 
-Examples on tool usage can be found in the [VSS Makefile](https://github.com/COVESA/vehicle_signal_specification/blob/master/Makefile) and in tool-specific documentation, if existing.
+See [usage](#usage) for how to start using it.
+
+## Usage
 
 General CLI help should be used for up to date info of how to use the tools.
 
 ```bash
-vspec --help # Help about global flags
-vspec export --help # Shows help for the export functionality
-vspec export json --help # Shows help for the json exporter
-# ...
+# Help for toplevel options and lists sub commands
+vspec --help
+
+# Help for export sub command options and lists sub commands
+vspec export --help
+
+# Help for json exporter options
+vspec export json --help
 ```
 
 Please check [here](./docs/vspec.md) for generic infos about exporters and their arguments
@@ -67,50 +83,72 @@ Examples on changes affecting compatibility
 
 ## Contributing
 
-### Prerequisites
-
-* If your environment behind a (corporate) proxy, the following environments variables must typically be set: `http_proxy` and `https_proxy` (including authentication e.g., `http://${proxy_username):$(proxy_password)@yourproxy.yourdomain`).
-* If using `apt` and you are behind a proxy, you may also need to configure proxy in `/etc/apt/apt.conf.d/proxy.conf`.
-
 ### Poetry
 
 We are using [poetry](https://python-poetry.org/docs/) or a package and venv handling system.
-Therefore a requirement to develop a tool is to install poetry on your host machine. For that you will need Python > 3 as well as pip.
+Therefore a requirement to develop a tool is to install poetry on your host machine.
 Check [here](https://python-poetry.org/docs/#installation) for official installation instructions. The recommended one is the following, however installing it through pip/pipx works aswell:
 
 ```bash
 curl -sSL https://install.python-poetry.org | python3 -
 ```
 
-You can then use the following command to install all dependencies and the `vss-tools` package:
+You can then use the following command in the root directory of `vss-tools` to install all dependencies:
 
 ```bash
 poetry install
 ```
 
-The call will create an `.venv` directory but does not automatically activate it.
-You can do that in various ways:
+Due to our [poetry.toml](./poetry.toml) the call will create a `.venv` directory but does not automatically activate it.
+
+You can use that venv in several ways, with or without the help of `poetry`:
 - `poetry shell`: Spawns a new subshell with the appropriate environment activated. After that you can directly call tools
 - `poetry run <tool>`: Runs the given tool in the virtual environment but does return to the current environment after that
-- `. $(poetry env info --path)/bin/activate`: Enables the virtual environment. Since we do store virtual envs directly with the tool the command can be simplified to `. .venv/bin/activate`. See [here](https://python-poetry.org/docs/basic-usage/#using-poetry-run) for more detailed information how to run poetry e.g. for Windows and how to exit/deactive it.
+- `. $(poetry env info --path)/bin/activate`: Enables the virtual environment. Since we do store virtual envs directly with the tool the command can be simplified to `. .venv/bin/activate`. See [here](https://python-poetry.org/docs/basic-usage/#using-poetry-run) for more detailed information how to run poetry e.g. for Windows and how to exit/deactivate it.
 - We also have an `.envrc` that automatically sources the `.venv` when available. Check [direnv](https://direnv.net/) for how to set it up.
 
+Examples (all from vss-tools root and after running `poetry install`):
+
+venv activation:
+```bash
+source .venv/bin/activate
+vspec --help
+```
+poetry shell:
+```bash
+poetry shell
+vspec --help
+```
+
+poetry run:
+```bash
+poetry run vspec --help
+```
+
+direnv:
+```bash
+vspec --help
+```
 
-## Installing additional tools
 
-If you intend to run testcases related to `vspec` proto exporter you need to install the protobuf compiler.
-Please follow official instructions for your OS. For Debian systems it would be:
+### Pre-commit
 
-```sh
+This project uses [pre-commit](https://pre-commit.com/) which helps formatting the source code in a streamlined way.
+It is very recommended to use it.
+To install hooks you can do `pre-commit install` from an [activated environment](#poetry).
+Hooks will then run every time you do a `git commit` on changed files.
+If you would like to run all hooks on all files you can do `pre-commit run --all`.
+Since `pre-commit` dependencies are installed in the virtual environment, it needs
+to be activated to be able to run them on a commit.
+
+
+### Installing additional tools
+
+If you intend to run test cases related to `vspec` proto exporter you need to install the protobuf compiler.
+Please follow [official instructions](https://github.com/protocolbuffers/protobuf) for your OS. For Debian systems it would be:
+
+```bash
 sudo apt update
 sudo apt install -y golang-go protobuf-compiler
 protoc --version  # Ensure compiler version is 3+
 ```
-
-## Pre-commit set up
-This repository is set up to use pre-commit hooks. After you clone the project, run `pre-commit install` to install pre-commit into your git hooks.
-pre-commit will now run on every commit. Every time you clone a project using pre-commit running pre-commit install should always be the first thing you do.
-
-## Building and installing with Pip
-
-For usage of VSS-Tools with Pip (PyPI) please see [README-PYPI.md](README-PYPI.md)