Créer la documentation de son projet facilement et gratuitement

ReadTheDocs Logo

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

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.

Emilien

https://unixfox.eu

Passionné de l'informatique, joueur assidu de Minecraft, administrateur système Linux et combattant du libre. Fondateur d'UniversUX.

View more posts from this author

Laissez-nous votre commentaire !

Share This