août 12
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.
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 !
- Créez un compte sur ReadTheDocs.org
- Une fois ceci fait, cliquez sur « créer de nouvelles docs«
- Ouvrez un terminal et créez un dossier sur votre ordinateur pour accueillir la documentation
mkdir docs - Créez un dépôt sur votre plate-forme préférée, par exemple Github
- Déplacez-vous vers le dossier de la documentation via votre terminal :
cd docs - 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.
- 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
- Lancez la commande de démarrage rapide de Sphinx
sphinx-quickstart
- É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. - Une fois ceci fait créez la documentation sous forme HTML
make html
- Et ensuite envoyez le tout vers votre dépôt !
git push
- Revenez sur votre navigateur internet et choisissez le nom de votre documentation
- Renseignez l’url (.git) du dépôt accueillant votre documentation
- Ajoutez s’y une description
- Choisissez la langue principale de votre documentation
- Renseignez l’url de votre projet (ex : le site de votre projet)
- Si vous souhaitez par la suite effectuer une association avec un sous-domaine de votre site, entrez ce sous-domaine
- Et enfin cliquez sur « Créer »
- 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.