docs: repo-wide documentation overhaul + analyze_file accepts str (v1.0.1)#31
Merged
Conversation
….0.1) A full audit of the repo against one goal — complete, clear for beginners, deep for specialists — plus a small API ergonomics fix. No detection-logic changes. API - FLACAnalyzer.analyze_file() now accepts a str path, not only pathlib.Path (coerced internally; matches the doc examples). Regression test added. Backward compatible. Docs — accuracy - README FAQ: removed non-existent `--repair` flag; documented automatic repair + the standalone `python -m flac_detective.repair`. Status badge -> stable (v1.0). - Verdict icons aligned to actual console output (WARNING is ❓ not ⚡) across README/docs. - __init__ docstring score /100 -> /150. Docs — depth (specialists) - technical-details.md: new "Rule 12 (CNN)" section (mid/side input, 7 kHz reliability gate), "Supported Formats" table, "Threshold Calibration" rationale (61->55), and an honest "what a verdict means" note (evidence levels, ~80-87% specificity). Docs — onboarding (beginners) - getting-started.md: ffmpeg as a per-OS prerequisite for ALAC/APE (FLAC/WAV never need it). - README: mid/side gloss + 0-150 score-scale explanation. Docs — navigation - docs index/README now link the ML case study (ml/README.md) and the formats roadmap. - CONTRIBUTING.md: worked "Implementing a New Scoring Rule" guide (Strategy pattern). Version bumped 1.0.0 -> 1.0.1 across version files + CITATION + CHANGELOG. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
v1.0.1 — Refonte documentaire du repo + ergonomie API
Audit complet du dépôt avec une seule boussole : une mine d'infos complète, limpide pour les débutants, pointue pour les spécialistes. Aucun changement de logique de détection.
API (petit fix utile)
FLACAnalyzer.analyze_file()accepte désormais unstr, plus seulement unpathlib.Path(coercition interne) — conforme à tous les exemples de la doc. Test de régression ajouté. Rétro-compatible.Docs — exactitude (bugs doc corrigés)
--repairinexistant → documenté la réparation automatique + la commande séparéepython -m flac_detective.repair.__init__: score/100→/150.Docs — profondeur (spécialistes)
technical-details.md: nouvelle section Rule 12 (CNN) (entrée mid/side, gate de fiabilité 7 kHz), table Formats supportés, et calibration des seuils (pourquoi SUSPICIOUS 61→55). Note honnête « ce qu'un verdict signifie » (niveaux de preuve, spécificité ~80-87 %).Docs — onboarding (débutants)
getting-started.md: ffmpeg en prérequis per-OS pour ALAC/APE (et FLAC/WAV n'en ont jamais besoin).Docs — navigation
ml/README.md) et la roadmap formats.CONTRIBUTING.md: guide concret « Implémenter une nouvelle règle » (Strategy pattern + où la câbler).Version 1.0.0 → 1.0.1 (version files + CITATION + CHANGELOG).
Checks gatés verts en local : black, isort, flake8=0, mypy clean (49 fichiers), tests OK.
🤖 Generated with Claude Code