update doc

.ruff.toml

@@ -66,7 +66,7 @@ exclude= [  # external projects
 
 [lint.per-file-ignores]
 "*/tests/**" = ["ARG", "S", "D", "SLF001"]
-"*/examples/**" = ["INP001"]  # no namespace
+"*/examples/**" = ["INP001", "ERA001"]  # no namespace + commented-out code
 "software/shepherd-calibration/**" = ["ERA001"]  # comments
 "software/time_sync_analyzer/**" = ["ERA001", "S301"]  # comments
 "software/shepherd-devicetest/**" = ["ERA001", "ARG001", "PLW0603", "F405", "F403", "ANN001"]

docs/conf.py

@@ -34,8 +34,8 @@
     "myst_parser",
     "sphinx_design",
     "sphinx_copybutton",
-#    "sphinxcontrib.typer",
-    #    "sphinx.ext.autosectionlabel",
+    # "sphinxcontrib.typer",
+    # "sphinx.ext.autosectionlabel",
 ]
 # TODO: check other sphinx-plugins (mentioned in pipfile) & breathe
 

docs/dev/contributing.md

@@ -108,40 +108,13 @@ As an alternative it often suffices to just pull the `index.html` into a browser
 
 ## Tests
 
-There is an initial testing framework that covers a large portion of the python code.
+There is a testing framework that covers a large portion of the python code.
 You should always make sure the tests are passing before committing your code.
+When changing lower level code it is also recommended to run the test-benches of the higher level tools.
+For a tutorial see the dedicated sections in the tool-documentations:
 
-To run the full range of python tests, have a copy of the source code on a BeagleBone.
-Build and install from source (see [](#dev_setup) for more).
-Change into the `software/python-package` directory on the BeagleBone and run the following commands to:
-
-- install dependencies of tests
-- run testbench
-
-```shell
-cd /opt/shepherd/software/python-package
-sudo pip3 install ./[tests]
-sudo pytest-3
-```
-
-Some tests (~40) are hardware-independent, while most of them require a BeagleBone to work (~100). The testbench detects the BeagleBone automatically. A small subset of tests (~8) are writing & configuring the EEPROM on the shepherd cape and must be enabled manually (`sudo pytest --eeprom-write`)
-
-The following commands allow to:
-
-- restartable run that exits for each error (perfect for debugging on slow BBone)
-- run single tests,
-- whole test-files or
-
-```shell
-sudo pytest-3 --stepwise
-
-sudo pytest-3 tests/test_sheep_cli.py::test_cli_emulate_aux_voltage
-
-sudo pytest-3 tests/test_sheep_cli.py
-```
-
-It is also recommended to **run the testbench of the herd-tool prior to releasing a new version**. See [project-page](https://github.com/orgua/shepherd/tree/main/software/shepherd-herd#testbench) for more info.
-
+- [sheep-testbench](#sheep-tests)
+- [herd-testbench](#herd-tests)
 
 ## Releasing
 

docs/index.rst

@@ -33,8 +33,6 @@ Welcome to SHEPHERD's documentation
    ./external/readme_core.md
    ./external/readme_data.md
 
-   ./external/readme_herd.md
-
    ./external/readme_cal.md
    ./external/readme_sync_analyzer.md
 

docs/tools/herd.md

@@ -1,20 +1,16 @@
 # Shepherd-Herd
 
-```{literalinclude} ../../software/shepherd-herd/README.md
-   :lines: 2-40
+```{include} ../../software/shepherd-herd/README.md
+   :start-line: 2
+   :end-line: 40
 ```
 
+(herd-config)=
 ## Configuration
 
 All `shepherd-herd` commands require the list of hosts on which to perform the requested action.
 
-To find active nodes a ping-sweep (in this example from .1 to .64) can be achieved with:
-
-```Shell
-nmap -sn 192.168.1.1-64
-```
-
-### Static
+### Static Config
 
 To simplify usage you should set up an ansible style, YAML-formatted inventory file named `herd.yml` in either of these directories (highest priority first):
 
@@ -29,24 +25,42 @@ Here is the example `herd.yml`-file in the `inventory` directory of the shepherd
 :language: yaml
 ```
 
-Only the `sheep:`-block is needed by the tool.
+:::{note}
+1. Only the `sheep:`-block is needed by the tool.
+2. IP-Addresses can be omitted if network is set up to resolve host-names.
+3. To find active nodes a ping-sweep (in this example from .1 to .64) can be achieved with:
+
+```Shell
+nmap -sn 192.168.1.1-64
+```
+:::
 
 After setting up the inventory, use `shepherd-herd` to check if all your nodes are responding correctly:
 
 ```Shell
-shepherd-herd -i herd.yml shell-cmd "echo 'hello'"
+shepherd-herd shell-cmd "echo 'hello'"
 ```
 
-:::{note}
-If you wish to 
+Or select individual sheep from the herd:
 
+```Shell
+shepherd-herd --limit sheep0,sheep2, shell-cmd "echo 'hello'"
+```
 
-### Dynamic
+### Dynamic Config
 
 This list of hosts is provided with the `-i` option, that takes either the path to a file or a comma-separated list of hosts (compare Ansible `-i`).
 
+```Shell
+shepherd-herd -i sheep0,sheep1,sheep2, shell-cmd "echo 'hello'"
+```
+
 ## Command-Line Interface
 
+:::{note}
+The tool has integrated help. For a full list of supported commands and options, run `shepherd-herd --help` and for more detail for each command `shepherd-herd [COMMAND] --help`.
+:::
+
 The command-line Interface is as follows:
 
 ```{eval-rst}
@@ -56,3 +70,24 @@ The command-line Interface is as follows:
 ```
 
 ## API
+
+```{eval-rst}
+.. autoclass:: shepherd_herd.Herd
+    :members:
+    :inherited-members:
+```
+
+(herd-tests)=
+## Tests
+
+For testing `shepherd-herd` there must be a valid `herd.yml` at one of the mentioned locations (look at [](#herd-config)) with accessible sheep-nodes (at least one).
+
+1. Navigate your host-shell into the package-folder and
+2. install dependencies
+3. run the testbench (~ 30 tests):
+
+```Shell
+cd shepherd/software/shepherd-herd
+pip3 install ./[tests]
+pytest
+```

docs/tools/sheep.md

@@ -1,4 +1,4 @@
-# Shepherd-Sheep-Tool
+# Shepherd-Sheep
 
 `shepherd-sheep` is the command line utility for locally controlling a single shepherd observer.
 Depending on your use-case you may not even need to directly interact with it. Use the `shepherd-herd` command line utility to orchestrate a group of shepherd observer remotely.
@@ -7,6 +7,10 @@ For using the tool, deploy the software as described in [](../user/getting_start
 
 ## Command-Line Interface
 
+:::{note}
+The tool has integrated help. For a full list of supported commands and options, run `shepherd-sheep --help` and for more detail for each command `shepherd-sheep [COMMAND] --help`.
+:::
+
 The command-line Interface is as follows:
 
 ```{eval-rst}
@@ -20,8 +24,8 @@ The command-line Interface is as follows:
 The shepherd-sheep API offers high level access to shepherd's functionality and forms the base for the two command line utilities.
 With the introduction of the [core-lib](https://pypi.org/project/shepherd-core/) the api was simplified and modernized with a model-based approach. The [pydantic](https://docs.pydantic.dev) data-models offer self-validating config-parameters with neutral defaults.
 
-For lower-level access, have a look at the [](#hrv-api) and [](#emu-api) below. There is a third option called `debug-api`, used i.e. by the programmer. 
-It will not be documented here. 
+For lower-level access, have a look at the [](#hrv-api) and [](#emu-api) below. There is a third option called `debug-api`, used i.e. by the programmer.
+It will not be documented here.
 To learn about the functionality [the source](https://github.com/orgua/shepherd/blob/main/software/python-package/shepherd_sheep/shepherd_emulator.py) should be consulted.
 
 ### Harvesting
@@ -58,7 +62,7 @@ from shepherd_sheep.logger import set_verbosity
 :pyobject: run_emulator
 ```
 
-The snippet is taken from the actual implementation in [sheep/init](https://github.com/orgua/shepherd/blob/main/software/python-package/shepherd_sheep/__init__.py) and references the [EmulationTask](https://github.com/orgua/shepherd-datalib/blob/main/shepherd_core/shepherd_core/data_models/task/emulation.py). 
+The snippet is taken from the actual implementation in [sheep/init](https://github.com/orgua/shepherd/blob/main/software/python-package/shepherd_sheep/__init__.py) and references the [EmulationTask](https://github.com/orgua/shepherd-datalib/blob/main/shepherd_core/shepherd_core/data_models/task/emulation.py).
 
 :::{note}
 TODO: add user/task-config and relink both tasks above
@@ -84,7 +88,7 @@ from shepherd_sheep.sysfs_interface import check_sys_access
 :pyobject: run_firmware_mod
 ```
 
-The snippet is taken from the actual implementation in [sheep/init](https://github.com/orgua/shepherd/blob/main/software/python-package/shepherd_sheep/__init__.py) and references the [FirmwareModTask](https://github.com/orgua/shepherd-datalib/blob/main/shepherd_core/shepherd_core/data_models/task/firmware_mod.py). 
+The snippet is taken from the actual implementation in [sheep/init](https://github.com/orgua/shepherd/blob/main/software/python-package/shepherd_sheep/__init__.py) and references the [FirmwareModTask](https://github.com/orgua/shepherd-datalib/blob/main/shepherd_core/shepherd_core/data_models/task/firmware_mod.py).
 
 ### Program Target
 
@@ -104,11 +108,11 @@ from shepherd_sheep.shepherd_debug import ShepherdDebug
 :pyobject: run_programmer
 ```
 
-The snippet is taken from the actual implementation in [sheep/init](https://github.com/orgua/shepherd/blob/main/software/python-package/shepherd_sheep/__init__.py) and references the [ProgrammingTask](https://github.com/orgua/shepherd-datalib/blob/main/shepherd_core/shepherd_core/data_models/task/programming.py). 
+The snippet is taken from the actual implementation in [sheep/init](https://github.com/orgua/shepherd/blob/main/software/python-package/shepherd_sheep/__init__.py) and references the [ProgrammingTask](https://github.com/orgua/shepherd-datalib/blob/main/shepherd_core/shepherd_core/data_models/task/programming.py).
 
 ### Example-Code
 
-This snippet shows the harvester and emulator instantiated with custom config-models. It was used as a 10h stress-test to find a memory leak. 
+This snippet shows the harvester and emulator instantiated with custom config-models. It was used as a 10h stress-test to find a memory leak.
 
 ```{literalinclude} ../../software/python-package/tests_manual/testbench_longrun.py
 :language: python
@@ -135,6 +139,38 @@ Source: [./tests_manual/testbench_longrun.py](https://github.com/orgua/shepherd/
     :inherited-members:
 ```
 
+(sheep-tests)=
+## Tests
+
+To run the full range of python tests, have a copy of the source code on a BeagleBone.
+Build and install from source (see [](#dev_setup) for more).
+Change into the `software/python-package` directory on the BeagleBone and run the following commands to:
+
+- install dependencies of tests
+- run testbench
+
+```shell
+cd /opt/shepherd/software/python-package
+sudo pip3 install ./[tests]
+sudo pytest-3
+```
+
+Some tests (~40) are hardware-independent, while most of them require a BeagleBone to work (~100). The testbench detects the BeagleBone automatically. A small subset of tests (~8) are writing & configuring the EEPROM on the shepherd cape and must be enabled manually (`sudo pytest --eeprom-write`)
+
+The following commands allow to:
+
+- restartable run that exits for each error (perfect for debugging on slow BBone)
+- run single tests,
+- whole test-files or
+
+```shell
+sudo pytest-3 --stepwise
+
+sudo pytest-3 tests/test_sheep_cli.py::test_cli_emulate_aux_voltage
+
+sudo pytest-3 tests/test_sheep_cli.py
+```
+
 ## Reference
 
 - [core-lib](https://github.com/orgua/shepherd-datalib/tree/main/shepherd_core/shepherd_core/data_models/task) data-models for custom tasks