housekeeping

Pipfile

@@ -16,7 +16,7 @@ pandas-stubs = "*"
 
 [packages]
 # NOTE: pip does not install these packages with as editable (-e), but pipenv does
-shepherd = {editable = true, path = "./software/python-package[test]"}
+shepherd = {editable = true, extras = ["test"], path = "./software/python-package"}
 shepherd-herd = {editable = true, path = "./software/shepherd-herd"}
 shepherd-cal = {editable = true, path = "./software/shepherd-calibration"}
 sphinx = "*"

README.md

@@ -48,7 +48,7 @@ We assume that your local machine is connected to the same network, that the nod
 
 If you haven't done it yet, clone this repository to your local machine:
 
-```
+```shell
 git clone https://github.com/orgua/shepherd.git
 ```
 
@@ -58,7 +58,7 @@ The tools are hosted on `PyPI` and require Python version >= 3.6.
 You'll also need to have `sshpass` installed on your machine, which is available through the package management system of all major distributions.
 Install the tools using `pip`:
 
-```
+```shell
 pip3 install ansible shepherd-herd
 ```
 
@@ -67,7 +67,7 @@ Adjust it to reflect your setup.
 You can arbitrarily choose and assign the hostnames (sheep0, sheep1, in this example) and the ansible_user (jane in this example).
 [**TODO:** update description with roles].
 
-```
+```yaml
 sheep:
   hosts:
     sheep0:
@@ -82,41 +82,41 @@ sheep:
 
 Now run the `bootstrap.yml` *Ansible* playbook, which sets the hostname, creates a user and enables passwordless ssh and sudo:
 
-```
+```shell
 ansible-playbook deploy/bootstrap.yml
 ```
 
 Finally, use the `deploy.yml` playbook to setup the *shepherd* software with the configured roles from inventory:
 
-```
+```shell
 ansible-playbook deploy/deploy.yml
 ```
 
 ## Usage
 
 Record two minutes of data:
 
-```
+```shell
 shepherd-herd harvester -d 120 -o recording.h5 -a mppt_voc
 ```
 The command starts the recording asynchronously and returns after all nodes have started recording.
 While the nodes are still recording (indicated by blinking of LED 1 and 2), prepare a directory on your local machine:
 
-```
+```shell
 mkdir ~/shepherd_recordings
 ```
 
 After the nodes stop blinking, you can retrieve the data to analyze it on your local machine:
 
-```
+```shell
 shepherd-herd retrieve recording.h5 ~/shepherd_recordings
 ```
 
 For a detailed description of the [HDF5](https://en.wikipedia.org/wiki/Hierarchical_Data_Format) based data format, refer to the [corresponding documentation](https://shepherd-testbed.readthedocs.io/en/latest/user/data_format.html).
 
 Finally, replay the previously recorded data to the attached sensor nodes, recording their power consumption:
 
-```
+```shell
 shepherd-herd emulator -o consumption.h5 recording.h5
 ```
 

software/shepherd-calibration/README.md

@@ -2,6 +2,14 @@
 
 *shepherd-cal* is the command line utility for calibrating and profiling a shepherd cape.
 
+---
+
+**Documentation**: [https://orgua.github.io/shepherd/](https://orgua.github.io/shepherd/)
+
+**Source Code**: [https://github.com/orgua/shepherd](https://github.com/orgua/shepherd)
+
+---
+
 ## Installation
 
 *shepherd-cal* is a pure python package and currently NOT available on PyPI.

software/shepherd-herd/README.md

@@ -1,11 +1,17 @@
+# Shepherd-Herd
 
 [![PyPiVersion](https://img.shields.io/pypi/v/shepherd_herd.svg)](https://pypi.org/project/shepherd_herd)
 [![CodeStyle](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 
-# shepherd-herd
+*Shepherd-herd* is the command line utility for controlling a group of shepherd nodes remotely through an IP-based network.
 
-*shepherd-herd* is the command line utility for controlling a group of shepherd nodes remotely through an IP-based network.
+---
 
+**Documentation**: [https://orgua.github.io/shepherd/](https://orgua.github.io/shepherd/)
+
+**Source Code**: [https://github.com/orgua/shepherd](https://github.com/orgua/shepherd)
+
+---
 
 ## Installation
 
@@ -31,7 +37,7 @@ This list of hosts is provided with the `-i` option, that takes either the path
 
 For example, save the following file in your current working directory as an ansible style, YAML-formatted inventory file named `herd.yml`.
 
-```
+```yaml
 sheep:
   hosts:
     sheep0: