docs: Restructure main README and extract CONTRIBUTING.md.

[Charly-sketch]

Closes #199

Description

Refactor the main README.md to improve clarity and maintainability by splitting it into dedicated documents.

• Extract testing guide into tests/TESTING.md
• Extract contribution guidelines into CONTRIBUTING.md
• Simplify README.md with overview, drivers table, quick start, and links
• Replace outdated API sections with links to per-driver README files
• Fix inconsistencies (driver names, paths, I2C bus, missing drivers)

No content removed — existing information has been reorganized into appropriate files.

Checklist

• mcp23009 should be mcp23009e (wrong directory name)

• vl53l1cx should be vl53l1x (wrong directory name)

• wsen_hids should be wsen-hids (directory uses hyphen, not underscore)

• wsen_pads should be wsen-pads (same)

• Missing drivers in the tree: hts221, gc9a01, bme280, steami_config

• API snippets use wrong class/method names (e.g. MCP23009 instead of MCP23009E, pads.pressure_hpa() instead of pads.pressure())

• machine.I2C(0) should be machine.I2C(1) (STeaMi uses I2C bus 1)

• CONTRIBUTING.md created with contribution guidelines extracted from README

• TESTING.md created with testing guide extracted from README

• README.md restructured: overview, drivers table, quick start, links

• All inaccuracies fixed (wrong names, missing drivers, wrong bus number)

• Links between files work (README links to CONTRIBUTING.md and TESTING.md)

• No content lost — everything from the old README is in one of the 3 files

[Copilot]

Pull request overview

Refactors the root documentation to make the main README.md shorter and move detailed guidance into dedicated docs, aligning driver references and usage guidance with the current repo layout.

Changes:

• Restructures README.md into an overview with a drivers/components table, quick start, and links to testing/contributing docs.
• Adds contribution guidelines in CONTRIBUTING.md (driver structure, conventions, CI, workflow).
• Adds testing guide in tests/TESTING.MD (running mock/hardware tests and reports).

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 6 comments.

File	Description
README.md	Replaced long per-driver sections with a components table, quick start, install guidance, and links to new docs.
tests/TESTING.MD	New testing guide describing how to run tests and generate reports.
CONTRIBUTING.md	New contribution guide extracted from README, documenting conventions and workflow.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[nedseb]

La direction est bonne (split README → CONTRIBUTING.md + TESTING.md) mais il y a pas mal de problèmes de cohérence et de qualité. On sent que le contenu a été en grande partie généré par un LLM et copié-collé sans relecture attentive. Prends le temps de relire chaque ligne généré par ton LLM et de vérifier que ce que tu écris correspond à la réalité du code car au final c'est toi qui en porte la responsabilité.

---

🔴 Problèmes bloquants

1. Le fichier s'appelle tests/TESTING.MD — le .MD est en majuscules

Sur un système case-sensitive (Linux, CI), [tests/TESTING.md](tests/TESTING.md) dans le README pointe vers TESTING.md mais le fichier s'appelle TESTING.MD. Le lien est cassé. Convention du projet : les extensions sont en minuscules (.md, .py, .yaml). Renomme en tests/TESTING.md.

2. Les deux fichiers n'ont pas de newline finale

CONTRIBUTING.md et TESTING.MD se terminent sans \n. C'est visible dans le diff : \ No newline at end of file. Ça provoque des warnings Git et peut casser certains outils. Ajoute une ligne vide à la fin de chaque fichier.

3. Le README perd le newline final aussi

La dernière ligne du README (- [mpremote Documentation]...) n'a plus de newline. Même problème.

4. Référence issue incorrecte

La PR dit Closes #199. L'issue #199 demande de restructurer le README principal ET de créer des liens vers les README de drivers. Tu fais la restructuration mais vérifie que toutes les demandes de l'issue sont bien couvertes. Si l'issue demandait aussi l'extraction du CONTRIBUTING, vérifie que c'était bien dans le scope.

---

🟡 Problèmes de cohérence avec le projet

5. CONTRIBUTING.md — arbre des fichiers incorrect

lib/
├── <driver_name>/
|    ├── <driver_name>
|    |    ├── __init__.py
|    |    ├── device.py
|    |    ├── exceptions.py    ← N'EXISTE PAS FORCEMENT
|    |    └── const.py

Quasi aucun driver du projet n'a de fichier exceptions.py. De plus, les barres verticales utilisent | au lieu de │ (caractère Unicode box-drawing), ce qui rend l'arbre visuellement moche.

Compare avec la structure réelle :

lib/<component>/
├── README.md
├── manifest.py
├── <module_name>/
│   ├── __init__.py
│   ├── const.py
│   └── device.py
└── examples/
    └── *.py

Note aussi que le README.md est au niveau du driver, pas à l'intérieur du sous-dossier.

6. CONTRIBUTING.md — exemples de commits FAUX

feat: add ism330dl driver           ← NE RESPECTE PAS LE FORMAT
fix: correct pressure conversion    ← PAREIL

Le format du projet est <scope>: <Description avec majuscule et point final.>. Pas feat: comme scope. Le scope est le nom du driver ou du domaine (ism330dl, docs, tests...). Tes exemples ne commencent pas par une majuscule et n'ont pas de point final. De plus, la section "Types" (feat, fix, docs, refactor, test) n'existe pas dans les conventions du projet — c'est du Conventional Commits, qui n'est pas le format utilisé ici.

Tes propres commits respectent le bon format (tests: Add mock scenarios for mcp23009e driver.) — utilise-les comme exemples !

7. CONTRIBUTING.md — ruff format n'est pas utilisé

ruff check . --fix

Le projet utilise ruff check uniquement. La commande ruff format n'est pas configurée ni utilisée.

8. CONTRIBUTING.md — section "Types" inventée

La section qui liste feat, fix, docs, refactor, test comme types de commits est une invention. Le CI valide uniquement le pattern ^[^!]+: [A-Za-z]+.+ .+\.$ — il n'y a aucune liste de types prédéfinis. Le scope est libre (nom du driver, docs, tests, ci...).

9. CONTRIBUTING.md — workflow propose de "Fork" systématiquement

1. Fork the repository
2. Create a branch for your feature

Si tu travaille directement sur le repo steamicc/micropython-steami-lib, le workflow est plutôt : créer une branche depuis main, pas forker. N'oublie pas que le document de contribution est le même que tu sois membre de l'organisation ou pas.

---

🟡 Problèmes de style et de rédaction

10. README — section "Quick start" manque d'explication

pip install mpremote
mpremote mount lib/ism330dl run lib/ism330dl/examples/basic_read.py

L'ancien README expliquait les étapes (installer mpremote, connecter la carte, monter le driver). Le nouveau README donne juste 2 commandes sans contexte. Un débutant ne comprendra pas. La phrase "Use mpremote to quickly run a driver example without installing anything on the board." est vague — sur quel board ? comment le connecter ?

11. README — la section Installation a des formulations redondantes

### Method 1: Using mpremote (temporary)
Use this method during development to run drivers without copying them to the board. (recommended for development)

puis juste en dessous :

This mounts the repository on the board filesystem so you can import and test drivers instantly.

3 phrases qui disent la même chose. Garde-en une seule claire.

12. README — section Testing trop minimaliste

Run the full test suite (mock + hardware):
pytest

pytest tout court ne fonctionne pas pour les tests hardware (il faut --port). Et pytest tout court ne filtre pas mock vs hardware. L'ancien README était bien plus utile avec les différentes commandes. Soit tu gardes les détails dans le README, soit tu renvoies vers TESTING.md mais avec une phrase qui explique la différence mock/hardware.

13. TESTING.md — séparateurs --- superflus

Les --- entre chaque section rendent le document lourd visuellement. En Markdown, les titres ## et ### suffisent à structurer le document. Les --- sont utilisés pour les thematic breaks, pas comme séparateurs de section. Ça ressemble à du contenu généré par LLM qui met des séparateurs partout.

14. CONTRIBUTING.md — double espace vide

Il y a deux lignes vides consécutives après la section "Coding conventions" et après la section "Continuous Integration". Une seule ligne vide entre les sections suffit.

---

💡 Contenu manquant

15. Table des drivers — liens vers des READMEs inexistants

La table pointe vers lib/bme280/README.md, lib/gc9a01/README.md, lib/im34dt05/README.md — ces fichiers n'existent pas. C'est correct de les lister dans la table (ce sont des composants de la carte) mais les liens seront des 404. Ajoute une note ou retire les liens pour les drivers pas encore implémentés.

16. HTS221 et WSEN-HIDS partagent l'adresse 0x5F

---

Résumé

#	Problème	Sévérité
1	TESTING.MD en majuscules	🔴 Bloquant
2	Pas de newline finale (2 fichiers)	🔴 Bloquant
3	README perd newline finale	🔴 Bloquant
4	Vérifier scope issue #199	🟡 À vérifier
5	exceptions.py inventé + arbre cassé	🔴 Bloquant
6	Exemples commits faux	🔴 Bloquant
7	ruff format pas utilisé	🟡 Incorrect
8	Section "Types" inventée	🔴 Bloquant
9	Fork vs branche directe	🟡 À vérifier
10	Quick start trop brusque	🟡 Qualité
11	Formulations redondantes	🟡 Style
12	Section Testing minimaliste	🟡 Qualité
13	--- séparateurs superflus	🟡 Style
14	Double espaces vides	🟡 Style
15	Liens vers READMEs inexistants	🟡 À traiter
16	HTS221/WSEN-HIDS même adresse	💡 Clarification

[nedseb]

Note supplémentaire sur la qualité de relecture

Charly, regarde les commentaires automatiques de Copilot sur cette PR. Le bot a trouvé 6 problèmes sans même exécuter le code :

1. Lien cassé TESTING.md vs TESTING.MD — Copilot l'a vu
2. Exemples de commits qui ne respectent pas le format — Copilot l'a vu et propose une correction
3. pytest présenté comme "mock + hardware" alors qu'il ne lance que les mock sans --port — Copilot l'a vu
4. Commande mpremote incorrecte qui monte le mauvais dossier — Copilot l'a vu
5. Driver layout qui ne distingue pas <driver_dir> et <module_name> (ex: wsen-hids vs wsen_hids) — Copilot l'a vu
6. pip install hardcodé au lieu de pointer vers le requirements.txt du CI — Copilot l'a vu

Si un robot détecte autant d'erreurs, c'est que la relecture humaine n'a pas eu lieu. Avant de soumettre une PR, prends l'habitude de :

1. Relire chaque ligne de ton diff (git diff --cached) comme si tu étais le reviewer
2. Vérifier les chemins en les tapant dans ton terminal (ls tests/TESTING.MD → tu verrais le problème de casse)
3. Tester les commandes que tu documentes (copie-colle dans un terminal et vérifie que ça marche)
4. Comparer avec le code réel quand tu documentes une structure ou une API (ouvre device.py, vérifie les noms de méthodes)

Le travail de fond est bon (la restructuration en 3 fichiers est la bonne approche), mais la qualité d'exécution doit monter d'un cran. Chaque PR que tu soumets est relue par d'autres personnes — respecte leur temps en faisant ta propre revue d'abord.

[nedseb]

@Charly-sketch Pense à documenter tes changements STP

[Charly-sketch]

• Rename folder structure : lib/<driver_folder>/
• Correct TESTING.MD link
• Correct commit examples format
• Correct pytest command

[nedseb]

Charly, voici le suivi point par point de la revue initiale (16 points) :

Points bloquants de la revue

#	Problème	Statut
1	TESTING.MD en majuscules	❌ Toujours TESTING.MD — le fichier n'a pas été renommé en TESTING.md. Le lien dans le README pointe vers tests/TESTING.MD mais la convention est .md en minuscules
2	Pas de newline finale	✅ Corrigé (commit fe897b1)
3	README perd newline finale	✅ Corrigé
5	exceptions.py inventé dans l'arbre	❌ Toujours présent. L'arbre dans CONTRIBUTING.md liste encore exceptions.py. La plupart des drivers n'ont pas ce fichier
6	Exemples de commits faux	⚠️ Partiellement corrigé. Les exemples ont un point final maintenant (Add ism330dl driver.) mais utilisent encore feat:, fix:, docs: comme scope au lieu du nom du driver. feat: Add ism330dl driver. devrait être ism330dl: Add driver.
8	Section "Types" inventée	❌ Toujours présente. La section feat/fix/docs/refactor/test n'existe pas dans les conventions du projet. À supprimer

Points de cohérence

#	Problème	Statut
4	Vérifier scope issue #199	Non vérifié
7	ruff format pas utilisé	✅ Retiré
9	Fork vs branche directe	❌ Toujours "Fork the repository"
10	Quick start trop brusque	❌ Pas modifié
11	Formulations redondantes	❌ Pas modifié
12	Section Testing minimaliste	⚠️ Le lien a été corrigé vers TESTING.MD mais pytest seul est toujours trompeur
13	Séparateurs --- superflus	Non bloquant, pas demandé en correction
14	Double espaces vides	❌ Toujours 2 lignes vides après "Coding conventions" et après "Continuous Integration"
15	Liens vers READMEs inexistants	Non bloquant, noté
16	HTS221/WSEN-HIDS même adresse	Non bloquant, noté

Résumé

Sur les 6 points bloquants, 2 sont corrigés (newlines) et 4 ne le sont pas :

1. Fichier toujours TESTING.MD au lieu de TESTING.md
2. exceptions.py toujours dans l'arbre
3. Section "Types" (feat/fix/docs) toujours là
4. Exemples de commits utilisent toujours les types comme scope

Tu as listé dans ta réponse "Correct commit examples format" mais les exemples dans le fichier n'ont pas changé. Relis le diff de ton propre commit pour vérifier que tes modifications sont bien enregistrées.

[Charly-sketch]

#	Problème	Commit	Message explicatif
1	TESTING.MD + lien README	docs: Rename Testing.md. docs: Correct link in main README for TESTING.	Renommage du fichier + correction du lien pour éviter les problèmes liés au case-sensitive et garantir un lien fonctionnel dans le README.
5	Arbre CONTRIBUTING incorrect (exceptions.py)	docs: Remove exception.py for CONTRUBUTING.	Suppression de exceptions.py de l’exemple pour refléter la structure réelle des drivers du projet.
6	Exemples de commits incorrects	docs: Rephrase commit example ism330dl: Add driver.	Correction des exemples pour respecter le format attendu (<scope>: Description. avec majuscule et point final).
9	Workflow CONTRIBUTING (fork vs branche)	docs: Correct workflow in contributing by create a branch from main.	Mise à jour du workflow pour utiliser une branche depuis main plutôt qu’un fork systématique.
10	Quick start trop minimaliste	docs : Extend main README Quick start section.	Ajout de contexte et d’explications pour rendre la section plus compréhensible pour les nouveaux utilisateurs.
11	Redondances dans README	docs: Remove dupplicates in main README.	Nettoyage des répétitions pour améliorer la lisibilité du README.
12	Section Testing minimaliste	docs: Correction README.	Corrigé dans le commit Corrections globales du README (cohérence, format, contenu).
13	Séparateurs --- inutiles	docs: Remove separation line in TESTING.md .	Suppression des séparateurs superflus pour alléger la structure du document.
14	Doubles lignes vides	docs: Remove double newLine in CONTRIBUTING.md .	Nettoyage des lignes vides en trop pour respecter les bonnes pratiques Markdown.
15	Liens vers READMEs inexistants	—	Choix de conserver les liens pour anticiper l’ajout futur des READMEs et éviter de devoir les recréer plus tard.
16	Adresse I2C identique	—	Vérification faite : les deux composants utilisent bien la même adresse I2C (0x5F). Aucun changement appliqué, point laissé en clarification.

[nedseb]

J'ai corrigé directement les points restants de ma revue qui n'avaient pas été traités (commit 004f3ca) :

Corrigé :

1. Arbre des fichiers — Remplacé les | par │ (box-drawing Unicode) et aligné sur la structure documentée dans CLAUDE.md (lib/<component>/README.md, manifest.py, <module_name>/, examples/)
2. Section "Types" supprimée — Il n'y a pas de types prédéfinis (feat, fix...) dans le projet. Le scope est libre (nom du driver ou domaine). La section a été remplacée par une explication claire.
3. Exemples de commits corrigés — fix: Correct pressure conversion in wsen-pads. → wsen-pads: Correct pressure conversion formula. Le scope est le nom du driver, pas un type conventionnel.
4. Liens vers README inexistants — Les 3 drivers non implémentés (im34dt05, bme280, gc9a01) n'ont plus de liens cassés, remplacés par *(not yet implemented)*.
5. Section Installation — Supprimé la redondance entre Quick start et "Method 1" qui disaient la même chose en 3 formulations différentes.
6. Branche d'exemple — feat/my-new-feature → my-new-feature (pas de préfixe feat/ imposé).

La PR est prête à merger.

[semantic-release-updater]

🎉 This PR is included in version 0.0.2 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀