Écrivez la documentation technique de votre projet

Dans le précédent chapitre, nous avons évoqué les bonnes pratiques pour écrire la documentation de notre code.

Dans ce chapitre, je vous propose d’aborder comment publier votre documentation en ligne avec GitHub et Read the Docs.

Utilisez Git comme un pro !

Pourquoi gérer son code avec Git ?

Pour rappel, Git est un logiciel de gestion de version de code qui permet de faciliter le travail collaboratif au sein d’une équipe.

Comment tirer le maximum de Git ? 

Tout d’abord, nous en avons parlé juste avant, chaque modification (ajout, suppression, etc.) est accompagnée d’un petit message lorsque que l’on commit son code. Vous remarquerez que ce petit message n’est pas optionnel, et je vous recommande de bien faire attention à la manière dont vous le rédigez.

En effet, l’ensemble des messages constitue un historique qui permet au premier coup d’œil de remonter le fil de décisions et de modifications du code, tant pour vous que pour vos collaborateurs.

Par exemple, en cas de merge avec une autre branche :

Merge branch 'java/addproduct' into main

Ou alors pour décrire une fonctionnalité :

feature: used to add a product to the shopping cart

Le README, vitrine de votre projet

Grâce à ce fichier, il faut qu’en quelques instants les contributeurs ou les visiteurs du projet comprennent l’objectif du travail présenté, ainsi que son contexte.

Ici, je vous donne quelques éléments que j’aime faire figurer dans mes README :

• vous pouvez utiliser des badges (comme For The Badge ou Shields) pour facilement labelliser votre projet, comme présenter son statut ou son avancement ;

• un titre et un rapide en-tête explicatif avec un snapshot, si besoin, sont un must ;

• l’équipe qui travaille sur le projet ;

• les technologies utilisées ;

• les aspects licence ;

• comment contribuer, s’il s’agit d’un projet open source.

Ces éléments ne sont pas exhaustifs, mais ils me paraissent indispensables.

Avant de finir ce chapitre, voici une trame de fichier README que je vous invite à suivre pour vos projets de code. Je l'ai construite à partir d'un projet hypothétique d'application de réveil, et vous y retrouverez tous les éléments présentés ci-dessus.

[![forthebadge](https://forthebadge.com/images/badges/cc-0.svg)](https://forthebadge.com) [![forthebadge](https://forthebadge.com/images/badges/made-with-javascript.svg)](https://forthebadge.com) [![forthebadge](https://forthebadge.com/images/badges/uses-css.svg)](https://forthebadge.com)

# Sleep Well : the smart alarm-clock app

Sleep Well aims at developing a smart alarm clock for iPhones that monitors your breathing rhythm while you sleep to determine your sleep cycles.

## Technologies
- JS
- CSS 
- React

## Contribute to the project

Sleep Well is an open source project. Feel free to fork the source and contribute with your own features.

## Authors

Our code squad : Francis & Stéphane

## Licensing

This project was built under the Creative Commons licence.

Voilà le résultat sur mon repository :

Après avoir vu comment utiliser Git pour une documentation efficace, je voudrais vous présenter Read the Docs, un outil très répandu dans la sphère du développement, que vous pourrez synchroniser avec Git pour améliorer votre travail collaboratif sur la documentation.

Read the Docs

Dans la pratique, vous pourrez créer, tester et mettre à jour la documentation à chaque commit.

Sans rentrer dans le détail, Read the Docs fonctionne grâce à 2 éléments :

• Sphinx, un des outils de génération de documentation de la communauté Python ; 

• un langage proche de Markdown, reStructuredText, qui permet d’écrire la documentation du code en plein texte.

Ci-dessous, je vous propose un exemple de syntaxe reStructuredText :

Sleep Well Documentation
========================

:Author: Francis
:Version: $1.0$
:License: Creative Commons  

Contents
------------

This documentation highlights the most important elements to **install** and to **configure** your app.

Technologies
------------

* JS
* CSS
* HMTL

Installing the app
------------------

...

Et voici le résultat avec un éditeur classique de reStructuredText :

Dans cet écosystème, Read the Docs permet d’ajouter à la puissance de Sphinx un lien avec Git pour assurer la gestion du versioning, la recherche plein texte et les fonctionnalités de Git. En tant que développeur au sein d’une équipe, l’association des 2 outils vous donne un ensemble d’outils très puissant pour collaborer sur la documentation.

Plus techniquement, associer votre compte Read the Docs avec un repository Git permettra de :

• cloner le dépôt ;

• créer une documentation de la branche master aux formats HTML et PDF ;

• indexer la documentation pour permettre les recherches plein texte ;

• créer des branches de la documentation si nécessaire. 

En résumé

Dans ce chapitre, nous avons vu que :

• le respect de quelques règles d’écriture lors des commits, ainsi qu’un README cohérent, vous permettront de tirer le maximum de Git et de votre documentation ;

• lier votre repository avec un outil comme Read the Docs améliorera encore cet écosystème en vous fournissant un ensemble d’outils très puissant pour collaborer au sein de votre équipe.

Dans ce chapitre, nous avons vu comment tirer le maximum des outils disponibles pour collaborer efficacement et publier votre documentation en ligne. 

Dans le dernier chapitre de cette partie, je vous invite à voir comment concevoir des documentation d’API de manière professionnelle.