Comment rédiger un Readme pour votre projet Python ?

Le Readme est un document présent dans la quasi totalité des projets Python. C’est à la fois un outil de communication et de documentation pour les développeurs. Quels chapitres doit-il contenir pour votre projet Python ? Comment écrire votre Readme en langage Markdown ?

Quels sont les objectifs d’un Readme pour votre projet Python ?

Le Readme consiste à informer les développeurs en une page. C’est un brève description de votre projet et non une documentation complète. Le Readme a pour objectif de donner une vision globale de votre projet Python. Il permet également d’informer la communauté de développeurs sur votre projet. Si vous travaillez sur un projet open source, un Readme bien rédigé va favoriser l’utilisation de votre programme et sa diffusion. Enfin le Readme accélère la reprise de votre projet si vous n’avez travaillé dessus pendant plusieurs semaines. Il sera plus facile de vous remémorer son fonctionnement.

Les objectifs du Readme :

  1. Donner une vision globale du projet
  2. Facilite le partage avec une communauté d’utilisateurs
  3. Accélérer la reprise du projet

Quelles sont les informations que doit contenir votre Readme ?

Bien qu’il n’y ait de règle spécifique ou de standard pour les projets Python, il existe des us et coutumes et du bon sens dans l’univers des développeurs. Voici un exemple de structure pour rédiger votre Readme.

1. Description générale du projet

Présentez en quelques ligne votre projet. Dans quel cadre vous l’avez réalisé ? A quoi sert-il ? Pourquoi ce projet ?

2. Configurations compatibles

Listez les configurations compatibles avec votre programme ou celles que vous avez pu tester. On notera :

  • les versions de Python compatibles
  • La version de l’OS (Windows 10, Ubuntu 20, Mac,..).

3. Installation du programme

Votre programme nécessite certainement l’usage de packages externes, la création d’une base de données ou une commande spécifique. Par exemple, l’installation de packages externes contenus dans votre fichier requirements.txt. Ajouter ces informations pour qu’un utilisateur puisse lancer votre programme sans encombre.

4. Fonctionnalités

Décrivez les fonctions de votre programme, que va-t-il réaliser ? Pour les applications avec une interface graphique vous pouvez ajouter des copies d’écrans de vos interfaces.

5. Démarrage du programme

Décrivez les opérations à réaliser ou les commandes pour lancer votre programme. En complément vous pouvez lister des commandes secondaires qui permettront à l’utilisateur d’exploiter votre programme sans entrer dans une documentation exhaustive.

Comment écrire votre Readme en langage Markdown ?

Le langage markdown est balisé, un peu comme le HTML. Il est facile à apprendre et permet de rédiger votre Readme. L’extension du fichier se termine en .md

Ci-dessous un exemple de code markdown qui vous permettra de rédiger votre Readme. Vous pouvez utiliser l'IED Pycharm. Il affiche le rendu de votre Readme.

...