Archives du mot-clé documentation

La documentation !

Lors de nombreuse conférence et très souvent au travail, un point important revient tout le temps :

Les tests et la documentation !

Je m’attarde ici sur la seconde partie. En effet, nous passons beaucoup de temps à coder… Mais sans une bonne documentation, notre code n’est pas facilement compréhensible par les autres. Pour une bibliothèque, son utilisation sera faible si la documentation est faible. Pour une application, le code devient legacy très rapidement et personne ne voudra plus le modifier.

Mais que dire de la documentation du langage de programmation utilisé ? Je mets le langage dans la catégorie des bibliothèques. Ceux qui me connaissent un peu sauront que je parle de PHP et plus particulièrement de la traduction de la documentation en français.

Il y a quelque temps, j’ai posté un twit pour inviter les bonnes volontés à venir traduire la documentation.

Après 31 Re-Twit (merci à eux) et 12 j’aime, il y a eu 2 contributions. Le résultat n’est pas si mal !

Au fil de la pérégrination de mon twit, Antoile Bellion a posé une question à laquelle je m’attendais.

La réponse fut pertinente de la part de l’un des traducteurs de la documentation PHP :

Pour ma part, je me suis attaché à réaliser un peu de ménage dans les fichiers à mettre à jour. En effet, certains fichiers à mettre à jour ne comportaient aucune (ou très peux de) modification. Il en reste encore beaucoup, mais le compteur est aujourd’hui à 913.

Pour les nouveaux fichiers à traduire, il reste 1258 fichiers en attente d’une première traduction.

Et vous, pourrez-vous nous aider à rattraper la documentation française de PHP ?

Le guide du traducteur (Anglais) et l’éditeur en ligne.

Compiler la doc de PHP

Travaillant actuellement sur la traduction française de la documentation de PHP, j’ai besoin d’appliquer les patchs que je produis sur la documentation actuelle pour me rendre compte du résultat.

Je vous partage les quelques commandes à réaliser pour extraire et générer la documentation.

Pour compiler la documentation française de PHP il est nécessaire d’avoir PHP, SVN et GIT d’installé sur la machine.

La première chose à faire est d’extraire le dépôt via le terminal :

L’accès est en lecture seul sur le dépôt, mais cela n’empêche pas de récupérer les sources.

Maintenant, entrer dans le dossier doc-fr puis récupérer l’outil PHD. Il permet la génération de la documentation en XHTML.

Il est possible de générer une première fois la documentation. Pour cela exécuter la commande configure suivante :

Enfin, pour générer les pages HTML, exécuter la commande suivante :

La génération de la documentation peut être lente, car il est nécessaire de tout indexer.

Afin de naviguer dans la documentation ainsi générée, il est possible d’utiliser le serveur intégré de PHP.

Ouvrez votre navigateur et saisir l’URL suivante http://127.0.0.1:8000