RootsLabs

More than a tool ! GitHub Google+ LinkedIn RSS

Comment publier sa documentation via ReadTheDocs ?

Progi1984 - Commentaires (3)

Dans le cadre de projets open-source, faire une documentation claire et lisible est un nécessité. Pour cela, ReadTheDocs permet de générer à partir de fichiers fournis au format Markdown une belle documentation.

ReadTheDocs : Logo

Créer sa documentation avec Sphinx

Il faut tout d’abord installer le paquet python-sphinx :

Après l’installation, allons dans le projet et créons le dossier de travail :

On initialise le projet avec Sphinx :

Après avoir commité votre dossier docs\ sur GitHub, nous allons configuré le projet sur ReadTheDocs.

Configurer son projet sur ReadTheDocs

Après avoir créé un compte, il faut aller sur le tableau de bord puis cliquer sur Import.

Je vais prendre PHPWord comme exemple pour lequel j’ai réalisé le début de la documentation.

La première partie du formulaire permet de définir le nom du projet, le dépôt et le type de dépôt du projet, suivi d’une description du projet.
ReadTheDocs : Import (1/2)

La seconde partie du formulaire permet de définir la langue principale du projet, le type de documentation (que j’ai laissé par défaut), l’URL du projet, et l’URL de la documentation (soit http://xxxx.readthedocs.org soit http://xxxx.domain.tld, si vous pointez un sous-domaine vers ReadTheDocs). On clique ensuite sur « Create ».
ReadTheDocs : Import (2/2)

Si on exécute actuellement un build manuellement, la documentation ne sera pas générée parce que ReadTheDocs ne sait pas où trouver la documentation dans le dépôt du projet. Pour cela, il faut aller dans les paramètres avancés (advanced settings) pour configurer le dossier où se trouve le fichier de configuration de la documentation. Dans notre exemple, c’est docs/conf.py.
ReadTheDocs : Configuration

Activer le webhook sur GitHub

Afin qu’à chaque commit, votre documentation soit regénéré automatiquement, il faut activer un webhook sur GitHub.
Pour cela, voici la procédure :

  • Aller sur la page « Settings » de votre projet ;
  • Aller sur l’onglet « Webhooks & Services » ;
  • Cliquer sur le bouton « Configure services » ;
  • Chercher « ReadTheDocs » dans la liste de services ;
  • Cocher la case « Active » et Valider.

Voilà, la documentation Markdown de votre projet a désormais plusieurs avantages : historisée via Git, automatiquement générée via ReadTheDocs, simple avec le format Markdown. Maintenant, à vous de jouer.

Commentaires

1. Yax, le 17 mars 2014 à 14:42

Je me suis retrouvé plusieurs fois à lire diverses docs sur le site ReadTheDocs mais je ne savais pas du tout ce qu’il y a derrière alors que je suis un fan de Markdown. Merci pour ce tuto très bien fait sur la génération d’un projet Sphinx et la configuration de ReadTheDocs.

2. Progi1984, le 17 mars 2014 à 14:53

@Yax :
Je confirme. J’ai eu du mal à comprendre la documentation de ReadTheDocs. Mais je me suis dit que pour PHPOffice, cela serait la solution la plus simple (sans hébergement propre). N’hésitez pas si il y a d’autres sujets que vous ne comprenez pas totalement et que vous cherchez à décrypter. Ce sera avec plaisir que je m’y attaquerais.

3. Comment publier sa documentation via ReadTheDoc..., le 17 mars 2014 à 23:39

[…] La documentation d'un projet open-source est importante. Via ReadTheDocs, nous allons avoir une documentation simple, historisée et automatiquement générée.  […]

Ajouter un commentaire

Commentaire :