Project metadata, refactoring, and adjustments to the README (#2)

## About

This patch intends to bring in a first iteration on matters enumerated
within GH-1. It does not change anything on the program's behaviour, it
only adjusts its layout, improves documentation, and adds a project
metadata file which will make it possible to install the program as a
package using `pip install`.

## Details

- Chore: Add project metadata and boilerplate
- Refactoring: Improve modularization and invocation semantics
- Improve README: Layout and wording

.gitignore

@@ -0,0 +1,5 @@
+.idea
+.venv*
+.coverage
+coverage.xml
+*.egg-info

CHANGES.md

@@ -0,0 +1,6 @@
+# Changes for temp-matrix
+
+## Unreleased
+
+## v0.0.1 - 2024-04-14
+- Make it work, and add documentation.

README.md

@@ -1,59 +1,77 @@
+# temp-matrix
+Temperature sensor matrix using Raspberry Pi, DS18B20, MQTT, Kotori DAQ,
+and Grafana. For bee hive monitoring.
+
 | View from outside | View from inside (sensor tip details) |
 |:----:|:----:|
 | ![Außen](https://community.hiveeyes.org/uploads/default/optimized/2X/f/f59f0149306b811f793627ec956c3e43c3758e51_2_334x500.jpeg)  | ![Innen](https://community.hiveeyes.org/uploads/default/optimized/2X/1/10f98dd272bd95940b311e22ef756114bd4efa04_2_333x500.jpeg) |
 
-# temp-matrix
-temperature matrix based on raspberry pi, python, 5x6 ds18b20, and grafana
 
-for development details see: [https://community.hiveeyes.org/t/laborprotokoll-4x5-temp-matrix-mit-ds18b20/5102/14](https://community.hiveeyes.org/t/laborprotokoll-4x5-temp-matrix-mit-ds18b20/5102/14)
+Lab protocol and development details:
+https://community.hiveeyes.org/t/laborprotokoll-4x5-temp-matrix-mit-ds18b20/5102
+
+
+## What's Inside
+* README.md - this file
+* LICENSE
+* temp-matrix_5x6.py - sensor reading and data logging to hiveeyes
+* temp-matrix_5x6-grafana_desktop.json - description of [Grafana Dashboard](https://swarm.hiveeyes.org/grafana/d/T49wHSaIk/mois-ex-wtf-test-ds18b20-5x6-temp-matrix-svg-pixmap?orgId=2&from=1712771622514&to=1712807415379)
+
+
+## Setup
+We recommend to install the program into a Python virtualenv.
+```shell
+python3 -m venv .venv
+source .venv/bin/activate
+pip install 'ds18b20-datalogger @ git+https://github.com/hiveeyes/temp-matrix.git'
+```
 
-## files
-  * README.md - this file
-  * LICENSE
-  * temp-matrix_5x6.py - sensor reading and data logging to hiveeyes
-  * temp-matrix_5x6-grafana_desktop.json - description of [grafana desktop](https://swarm.hiveeyes.org/grafana/d/T49wHSaIk/mois-ex-wtf-test-ds18b20-5x6-temp-matrix-svg-pixmap?orgId=2&from=1712771622514&to=1712807415379)
+In this spirit, you keep the installation separate from your system Python, so
+you can easily nuke it and start from scratch in case anything goes south.
 
-## sensor wiring
-be aware that you might have to ajust your resistors size.
-with 30 sensors i had erratic sensor mapping using a 4.7k resistor.
-i am getting valid mapping using a 2.2k resistor.
+Prerequisites: This program needs the `paho-mqtt` package.
+https://pypi.org/project/paho-mqtt/#installation
 
-## sensor mapping
-[https://community.hiveeyes.org/t/ds18b20-temperatur-sensoren-am-one-wire-bus-anordnen/1399
-](https://community.hiveeyes.org/t/ds18b20-temperatur-sensoren-am-one-wire-bus-anordnen/1399)
 
-## data publishing
-paho-mqtt required: [https://pypi.org/project/paho-mqtt/#installation](URL)
+## Operations
+
+### Sensor Wiring
+Be aware that you might have to adjust your resistors size.
+With 30 sensors i had erratic sensor mapping using a 4.7k resistor.
+I am getting valid mapping using a 2.2k resistor.
+
+### Sensor Mapping
+https://community.hiveeyes.org/t/ds18b20-temperatur-sensoren-am-one-wire-bus-anordnen/1399
+
+### Data Publishing
 
     ssh youruser@yourpi
     screen
     cd temp-matrix
     source paho-mqtt/bin/activate
     python temp-matrix_5x6.py`
 
-### mqtt data upload to hiveeyes
-[https://community.hiveeyes.org/t/daten-per-mqtt-und-python-ans-backend-auf-swarm-hiveeyes-org-ubertragen/94/6](https://community.hiveeyes.org/t/daten-per-mqtt-und-python-ans-backend-auf-swarm-hiveeyes-org-ubertragen/94/6)
+### MQTT data upload to Hiveeyes
+https://community.hiveeyes.org/t/daten-per-mqtt-und-python-ans-backend-auf-swarm-hiveeyes-org-ubertragen/94/6
 
-### format your array
-[https://community.hiveeyes.org/t/how-to-visualize-2-dimensional-temperature-data-in-grafana/974/9
-](https://community.hiveeyes.org/t/how-to-visualize-2-dimensional-temperature-data-in-grafana/974/9)
+### Format your array
+https://community.hiveeyes.org/t/how-to-visualize-2-dimensional-temperature-data-in-grafana/974/9
 
      matrix = [[temp_ir_1_1, temp_ir_1_2, temp_ir_1_3, temp_ir_1_4, temp_ir_1_5, temp_ir_1_6], \
           [temp_ir_2_1, temp_ir_2_2, temp_ir_2_3, temp_ir_2_4, temp_ir_2_5, temp_ir_2_6], \
           [temp_ir_3_1, temp_ir_3_2, temp_ir_3_3, temp_ir_3_4, temp_ir_3_5, temp_ir_3_6], \
           [temp_ir_4_1, temp_ir_4_2, temp_ir_4_3, temp_ir_4_4, temp_ir_4_5, temp_ir_4_6], \
           [temp_ir_5_1, temp_ir_5_2, temp_ir_5_3, temp_ir_5_4, temp_ir_5_5, temp_ir_5_6]]
 
-## data visualizing (grafana)
-[https://swarm.hiveeyes.org/grafana/d/Y9PcgE4Sz/mois-ex-wtf-test-ir-sensor-svg-pixmap-copy
-](https://swarm.hiveeyes.org/grafana/d/Y9PcgE4Sz/mois-ex-wtf-test-ir-sensor-svg-pixmap-copy)
-
-## bonus: sensors offsets
-[https://community.hiveeyes.org/t/temperatursensoren-justieren-kalibrieren/1744/2
-](https://community.hiveeyes.org/t/temperatursensoren-justieren-kalibrieren/1744/2)
-
-
+## Data visualization in Grafana
+https://swarm.hiveeyes.org/grafana/d/Y9PcgE4Sz/mois-ex-wtf-test-ir-sensor-svg-pixmap-copy
 
+## Bonus: Sensor offsets
+https://community.hiveeyes.org/t/temperatursensoren-justieren-kalibrieren/1744/2
 
+## Contributing
 
+In order to learn how to start hacking on this program, please have a look at the
+documentation about how to install a [development sandbox](./docs/sandbox.md).
 
+Contributions of any kind are always welcome and appreciated. Thank you.

docs/sandbox.md

@@ -0,0 +1,21 @@
+# Development Sandbox
+
+## Install
+```shell
+git clone https://github.com/hiveeyes/temp-matrix
+python3 -m venv .venv
+source .venv/bin/activate
+pip install --editable='.[develop,docs,release,test]'
+```
+
+## Software tests
+Run all linters, and invoke the test suite.
+```shell
+poe check
+```
+
+## Format code
+Run all code formatters.
+```shell
+poe format
+```

pyproject.toml

@@ -0,0 +1,208 @@
+[build-system]
+build-backend = "setuptools.build_meta"
+requires = [
+  "setuptools>=42", # At least v42 of setuptools required.
+  "versioningit",
+]
+
+[tool.versioningit.vcs]
+method = "git"
+default-tag = "0.0.0"
+
+[project]
+name = "ds18b20-datalogger"
+description = "Temperature sensor matrix using Raspberry Pi, DS18B20, MQTT, Kotori DAQ, and Grafana. For bee hive monitoring."
+readme = "README.md"
+keywords = [
+  "beehive monitoring",
+  "ds18b20",
+  "temperature matrix",
+  "sensor network",
+  "raspberry pi",
+  "mqtt",
+  "kotori daq",
+  "grafana",
+]
+license = { file = "LICENSE" }
+authors = [
+  { name = "The Hiveeyes Developers", email = "[email protected]" },
+]
+requires-python = ">=3.7"
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "License :: OSI Approved :: GNU General Public License (GPL)",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.7",
+  "Programming Language :: Python :: 3.8",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: Implementation :: CPython",
+  "Topic :: Education",
+  "Topic :: File Formats",
+  "Topic :: Scientific/Engineering",
+  "Topic :: Text Processing",
+]
+dynamic = [
+  "version",
+]
+dependencies = [
+  "paho-mqtt<2",
+]
+[project.optional-dependencies]
+develop = [
+  "black<25",
+  "mypy<1.10",
+  "poethepoet<0.26",
+  "pyproject-fmt<1.8",
+  "ruff<0.4",
+  "validate-pyproject<0.17",
+]
+docs = [
+]
+release = [
+  "build<2",
+  "keyring",
+  "twine<6",
+]
+test = [
+  "pytest<9",
+  "pytest-cov<6",
+]
+[project.urls]
+changelog = "https://github.com/hiveeyes/temp-matrix/blob/main/CHANGES.md"
+documentation = "https://ds18b20-datalogger.readthedocs.io/"
+homepage = "https://ds18b20-datalogger.readthedocs.io/"
+repository = "https://github.com/hiveeyes/temp-matrix"
+
+[tool.black]
+line-length = 120
+
+[tool.coverage.run]
+branch = false
+omit = [
+  "tests/*",
+]
+source = ["ds18b20_datalogger"]
+
+[tool.coverage.report]
+fail_under = 0
+show_missing = true
+
+[tool.mypy]
+packages = ["ds18b20_datalogger"]
+exclude = [
+]
+check_untyped_defs = true
+implicit_optional = true
+install_types = true
+no_implicit_optional = true
+non_interactive = true
+show_error_codes = true
+strict_equality = true
+warn_unused_ignores = true
+warn_redundant_casts = true
+
+[tool.pytest.ini_options]
+addopts = "-rA --verbosity=3 --cov --cov-report=term-missing --cov-report=xml"
+minversion = "2.0"
+log_level = "DEBUG"
+log_cli_level = "DEBUG"
+log_format = "%(asctime)-15s [%(name)-36s] %(levelname)-8s: %(message)s"
+testpaths = [
+  "ds18b20_datalogger",
+  "tests",
+]
+xfail_strict = true
+markers = [
+]
+
+[tool.ruff]
+line-length = 120
+
+lint.select = [
+  # Pycodestyle
+  "E",
+  "W",
+  # Pyflakes
+  "F",
+  # isort
+  "I",
+  # Bandit
+  "S",
+  # flake8-quotes
+  "Q",
+  # eradicate
+  "ERA",
+  # flake8-2020
+  "YTT",
+  # print
+  "T20",
+  # return
+  "RET",
+  # pyupgrade
+  # "UP",
+  # flake8-commas
+  # "COM",
+  # future-annotations
+  # "FA",
+  # flake8-type-checking
+  "TCH",
+  # flake8-unused-arguments
+  # "ARG",
+  # flake8-use-pathlib
+  # "PTH"
+]
+
+lint.extend-ignore = [
+  # zip() without an explicit strict= parameter
+  "B905",
+  # df is a bad variable name. Be kinder to your future self.
+  "PD901",
+  # Unnecessary variable assignment before `return` statement
+  "RET504",
+  # Unnecessary `elif` after `return` statement
+  "RET505",
+]
+
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["S101"]  # Allow use of `assert`, and `print`.
+
+[tool.setuptools.packages.find]
+namespaces = false
+
+
+# ===================
+# Tasks configuration
+# ===================
+
+[tool.poe.tasks]
+
+check = [
+  "lint",
+  "test",
+]
+
+format = [
+  { cmd = "black ." },
+  # Configure Ruff not to auto-fix (remove!):
+  # unused imports (F401), unused variables (F841), `print` statements (T201), and commented-out code (ERA001).
+  { cmd = "ruff check --fix --ignore=ERA --ignore=F401 --ignore=F841 --ignore=T20 --ignore=ERA001 ." },
+  { cmd = "pyproject-fmt --keep-full-version pyproject.toml" },
+]
+
+lint = [
+  { cmd = "ruff check ." },
+  { cmd = "black --check ." },
+  { cmd = "validate-pyproject pyproject.toml" },
+  { cmd = "mypy" },
+]
+
+release = [
+  { cmd = "python -m build" },
+  { cmd = "twine upload dist/*.tar.gz dist/*.whl" },
+]
+
+test = { cmd = "pytest" }