french-typo 1.0.0

Moteur de correction typographique française

= French Typo
Dhrions
0.2.0
:sectnums:
:toc:
:toclevels: 3
:toc-title: Sommaire
:description: Moteur de correction typographique française (core Python, CLI, intégrations)
:keywords: typographie française, espaces insécables, Python, CLI, Anki, AsciiDoc
:icons: font

ifdef::env-github[]
image:https://img.shields.io/badge/version-0.2.0-blue[]
image:https://img.shields.io/badge/license-MIT-green[]
image:https://img.shields.io/badge/python-3.8%2B-blue[]
endif::[]

== Introduction

**French Typo** est un moteur de correction typographique française écrit en Python.

Il applique automatiquement les règles typographiques françaises usuelles (conformes au
link:https://les-unpertinents.fr/Manuscrits/Lexique%20des%20r%C3%A8gles%20typographiques%20en%20usage%20%C3%A0%20l%27Imprimerie%20nationale2.pdf[lexique de l’Imprimerie nationale]) :

* espaces insécables avant les ponctuations doubles (`: ; ? ! % €`),
* normalisation des unités (`KM` → `km`, `KG` → `kg`, etc.),
* formatage des ordinaux (`1er` → `1<sup>er</sup>`, `n°4` → `n<sup>o</sup>4`),
* suppression des espaces multiples,
* gestion des guillemets français (« »).

Le projet est structuré autour :
* d’un **core Python pur**, réutilisable partout ;
* d’une **CLI** pour le traitement de fichiers ;
* d’**adaptateurs** pour des environnements spécifiques (Anki, AsciiDoc).

---

== Fonctionnalités

* ✔️ Moteur typographique indépendant (sans dépendance UI)
* ✔️ API Python simple et stable
* ✔️ Interface en ligne de commande
* ✔️ Support d’AsciiDoc
* ✔️ Intégration Anki (HTML + cloze)
* ✔️ Tests unitaires couvrant le core

---

== Installation

=== Installation via pip (recommandée)

[source,bash]
----
pip install french-typo
----

---

== Utilisation

=== Utilisation en tant que bibliothèque Python

[source,python]
----
from french_typo.core.formatter import format_text
from french_typo.core.profiles import TypoProfile

text = "Voir n°4 : 10 KM et article 5."
result = format_text(text)

print(result)
# Voir n<sup>o</sup>&nbsp;4&nbsp;: 10&nbsp;km et article&nbsp;5.
----

=== Profils disponibles

* `TypoProfile.PLAIN` : texte brut
* `TypoProfile.ANKI` : HTML + cloze Anki
* `TypoProfile.ASCIIDOCT` : texte AsciiDoc

[source,python]
----
format_text("« {{c1::test}} »", profile=TypoProfile.ANKI)
----

---

=== Utilisation via la CLI

French Typo fournit une commande `french-typo` pour corriger des fichiers AsciiDoc.

[source,bash]
----
french-typo mon_fichier.adoc
----

Ou récursivement sur un dossier :

[source,bash]
----
french-typo docs/
----

Les fichiers sont modifiés *in place*.

---

== Intégrations

=== Anki

Le dépôt contient une intégration Anki historique (`format_anki_notes/`), qui utilise le moteur
`french_typo.core` pour formater les champs des notes :

* formatage d’une note individuelle ;
* formatage par lot depuis le navigateur ;
* gestion des cloze (`{{c1::...}}`) et du HTML.

⚠️ Cette partie dépend de l’API Anki (`aqt`) et **n’est pas incluse dans le paquet PyPI**.

---

=== AsciiDoc

L’adaptateur AsciiDoc permet de corriger automatiquement :

* les paragraphes standards ;
* en ignorant les blocs littéraux (`----`) ;
* en ignorant les commentaires (`//`).

---

== Architecture du projet

[source]
----
french-typo/
├── french_typo/
│   ├── core/              # Moteur typographique pur
│   ├── adapters/          # Intégrations (Anki, AsciiDoc)
│   └── cli.py             # Interface CLI
├── format_anki_notes/     # Add-on Anki (hors PyPI)
└── tests/                 # Tests unitaires
----

---

== Développement

=== Installation pour le développement

[source,bash]
----
git clone https://github.com/dhrions/french-typo.git
cd french-typo
python -m venv env
source env/bin/activate
pip install -e .
pip install -r requirements.txt
----

=== Exécuter les tests

[source,bash]
----
pytest
----

---

== Philosophie du projet

* séparation stricte entre **moteur** et **interfaces** ;
* API simple, explicite, testée ;
* aucune dépendance lourde dans le core ;
* extensible vers d’autres formats (Markdown, LaTeX, etc.).

---

== Licence

Ce projet est distribué sous licence MIT.  
Voir le fichier link:LICENSE[LICENSE].