Créer la documentation de son projet facilement et gratuitement

ReadTheDocs ou plus tôt Lisez les docs en français propose sa propre plate-forme d’hébergement de milliers de documentations et peut-être un jour la votre ?

Cet outil est très simple à utiliser, tout ce dont vous aurez besoin est une simple connaissance de github ou autre plate-forme de git / mercurial et un peu de travail.

Aperçu de la documentation

ReadTheDocs propose sa propre plate-forme d’hébergement des documentations mais je vous montrerez en fin d’article comment l’héberger sur sa propre machine. L’outil permet aussi d’associer un CNAME avec un sous-domaine vous appartenant.

Commençons donc à créer notre propre documentation !

1. Créez un compte sur ReadTheDocs.org
2. Une fois ceci fait, cliquez sur « créer de nouvelles docs« 
3. Ouvrez un terminal et créez un dossier sur votre ordinateur pour accueillir la documentation
   mkdir docs
4. Créez un dépôt sur votre plate-forme préférée, par exemple Github
5. Déplacez-vous vers le dossier de la documentation via votre terminal :
   cd docs
6. Clonez votre répertoire git / mercurial, dans le cas de Github :

   git clone https://github.com/utilisateur/nom_du_dépôt.git

   Note : Remplacez utilisateur par votre nom d’utilisateur et nom_du_dépôt par le nom de votre dépôt.

7. Installez Sphinx

   easy_install -U sphinx

   Note : Sous Debian & dérivés (Ubuntu, Linux mint), installez les outils de Python

   sudo apt-get install python-setuptools

8. Lancez la commande de démarrage rapide de Sphinx

   sphinx-quickstart

9. Éditez le fichier index.rst pour y ajouter les diverses informations à propos de votre projet.
   Note : Voici quelques aides à propos de cette partie :  reStructuredText ou ce template.
10. Une fois ceci fait créez la documentation sous forme HTML

    make html

11. Et ensuite envoyez le tout vers votre dépôt !

    git push

12. Revenez sur votre navigateur internet et choisissez le nom de votre documentation
13. Renseignez l’url (.git) du dépôt accueillant votre documentation
14. Ajoutez s’y une description
15. Choisissez la langue principale de votre documentation
16. Renseignez l’url de votre projet (ex : le site de votre projet)
17. Si vous souhaitez par la suite effectuer une association avec un sous-domaine de votre site, entrez ce sous-domaine
18. Et enfin cliquez sur « Créer »
19. Cliquez sur le bouton Afficher les docs pour afficher votre documentation

Pour associer un sous-domaine via CNAME, il faut simplement créer un CNAME avec l’url : nom_de_votre_documentation.readthedocs.org.
Plus d’infos : alternate_domains.html

ReadTheDocs a même pensé à vous si vous possédez votre propre machine du type VPS ou bien machine dédié et que vous voulez héberger vous même votre documentation : install.html.

Si vous êtes d’âme chercheur et perfectionniste, vous pourrez changer le thème par défaut de votre documentation avec ceux proposés par Sphinx : sphinx-doc.org/theming.html.