simplify documentation

README.md

@@ -8,8 +8,6 @@ This package connects the [bfabric](https://fgcz-bfabric.uzh.ch/bfabric/) system
 The [bfabricShiny](https://github.com/cpanse/bfabricShiny) R package is an extension and provides code snippets and sample implementation for a seamless R shiny bfabric integration.
 For more advanced users the *bfabricPy* package also provides a powerful query interface on the command-line though using the provided scripts.
 
-## Install
-
 ## CheatSheet
 
 ### Read

docs/contribute.md

@@ -0,0 +1,19 @@
+# Contribute
+
+This page describes some information relevant for contruibuting to bfabricPy.
+
+## Development install
+
+You should install the `dev` group as it contains some extra packages for running the tests.
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Running tests
+
+With `nox` and `uv` installed, it is as simple as running `nox` in the project root without any arguments.
+
+## Integration tests
+
+Note that integration tests have been moved to a separate repository. Please contact us if you are interested.

docs/index.md

@@ -4,43 +4,25 @@ This package connects the [bfabric](https://fgcz-bfabric.uzh.ch/bfabric/) system
 The [bfabricShiny](https://github.com/cpanse/bfabricShiny) R package is an extension and provides code snippets and sample implementation for a seamless R shiny bfabric integration.
 For more advanced users the *bfabricPy* package also provides a powerful query interface on the command-line though using the provided scripts.
 
-## Installation
-
-The package can be installed like any other Python package, so if you are familiar you might not need to read this section.
-Currently, it's only available from GitHub.
-
-The best way to install the package depends on your use case, i.e. whether you want to:
-
-1. Use the command line scripts
-2. Use the Python API
-3. Develop on the package
-
-The command line scripts are currently included in all cases.
+Please see below for how to install bfabricPy.
 
-### Command line scripts
+## Installation
 
-To use the command line scripts, it's recommended to install `bfabricPy` with [pipx](https://pipx.pypa.io/).
-If you don't have `pipx` installed, refer to the [pipx documentation](https://pipx.pypa.io/stable/installation/) for instructions.
+The package is not available on PyPI as of now, but can be installed directly from GitHub and a `stable` branch is available for your convenience.
 
-You can execute a command using a specific version of `bfabricPy` with the `pipx run` command.
-This command handles the dependencies of multiple concurrent installations:
+If you are only interested in running the command line scripts, installation with `pipx` is recommended as it will create a separate virtual environment for bfabricPy and make it possible to upgrade your installation later easily.
 
 ```bash
-pipx run --spec "git+https://github.com/fgcz/bfabricPy.git@stable" bfabric_read.py --help
+pipx install "git+https://github.com/fgcz/bfabricPy.git@stable"
 ```
 
-To install a specific version of bfabricPy on your system and make the command available without `pipx run` prefix, use the following command:
+Note that `pipx` is also useful in scripts, if you want to run a particular version without forcing the global installation of that version (simply replace "stable" with a tag of your chosing):
 
 ```bash
-pipx install "git+https://github.com/fgcz/bfabricPy.git@stable"
-bfabric_read.py --help
+pipx run --spec "git+https://github.com/fgcz/bfabricPy.git@stable" bfabric_read.py --help
 ```
 
-### Python API
-
-If you're interested in using the Python API of `bfabricPy`, you have two options:
-
-#### 1. Configure it in your `pyproject.toml` file.
+If you want to add it to a `pyproject.toml` the syntax for specifying a git dependency is as follows:
 
 ```toml
 [project]
@@ -49,23 +31,9 @@ dependencies = [
 ]
 ```
 
-#### 2. Install the `bfabricPy` package directly using pip.
-
-```bash
-pip install git+https://github.com/fgcz/bfabricPy.git
-```
-
-### Development
-
-As a bfabricPy developer: (i.e. an editable install)
-
-```{bash}
-pip install -e ".[dev]"
-```
-
 ## Configuration
 
-Create a file as follows: (note: the password is not your login password, but the web service password)
+Create a file as follows: (note: the password is not your login password, but the web service password available on your profile page)
 
 ```{yaml}
 # ~/.bfabricpy.yml