Pour faire suite à mon précédent article, voici une courte vidéo (4min) tutoriel sur la façon de proposer une correction à une faute ou une erreur présente dans la documentation de PHP.
Dans cette vidéo, j’utilise un exemple. La page de documentation de la fonction « openssl_decrypt » contient une erreur et je vous montre comment la modifier pour proposer un patch de correction.
La vidéo est disponible sur YouTube.
Depuis que je développe des logiciels, je prends toujours du temps pour écrire la documentation de mes applications. Qu’elle soit technique ou qu’elle soit pour l’utilisateur, j’écris la documentation en plus des lignes de code. Depuis novembre 2017, je contribue plus activement à la documentation française de PHP.
Pour ceux qui ne connaissent pas, PHP est un langage de programmation informatique très utilisé sur Internet pour écrire des sites web. Environ 80% des sites sont écrits en PHP.
En effet, pour un projet comme PHP, la documentation est primordiale. C’est le point d’entrée de tout nouvel utilisateur. La documentation est consultée chaque jour par de nombreux développeurs amateurs ou professionnels. Disposer d’une documentation dans la langue natale de l’utilisateur est un atout pour PHP.
Cependant, il est possible que lors de votre navigation, dans la documentation vous rencontriez des fautes de français, des erreurs de traduction. Sachez que vous pouvez soumettre une demande de correction.
Pour proposer une correction, cliquer sur le lien « edit » placé sous le menu de sélection de la langue.
Vous serez redirigé vers l’éditeur en ligne de la documentation de PHP. Clique alors sur le bouton « anonymous login » pour vous connecter sans avoir besoin d’un compte.
L’éditeur se charge et ouvre la page sur laquelle vous étiez.
La documentation de PHP est écrite dans des fichiers textes structurés grâce au langage XML. Vous le reconnaîtrez rapidement dans l’éditeur, car le XML est en couleur (vert, bleu, rouge, marron …).
Dans la page, qui s’est ouverte, recherchez la faute puis corrigez-la. Enregistrer votre modification en cliquant sur la disquette 
située en haut de la zone de modification.
Maintenant, votre travail est dans la section « travaux en cours ». Cette section est présente dans la colonne de gauche de l’éditeur. Cliquer sur son titre pour afficher son contenu.
Maintenant que la correction est effectuée. Il est nécessaire de la soumettre aux relecteur et traducteur de la documentation française. Pour cela, il est nécessaire d’ajouter le fichier modifié dans un « patch » (équivalent à une « pull request »). Tant que vous ne soumettez pas vos modifications via un patch, elles ne peuvent pas être validées et les relecteurs ne savent pas si vous avez terminé votre travail.
Pour ajouter le fichier dans un patch, réaliser un clic-droit sur le fichier visible dans la section « Travaux en cours » de l’éditeur en ligne puis choisir « Ajouter ce fichier dans un patch » dans le menu qui c’est affiché, puis cliqué sur « Ajouter dans un nouveau patch ».
Une fenêtre s’ouvre pour vous demander des informations complémentaires à la modification.
Saisissez un nom pour votre patch, une courte description, et pour finir une adresse courriel. Cette adresse est utilisée pour vous prévenir lors de l’application du patch ou de son rejet, mais aussi pour vous contacter pour vous remercier ou demander plus d’information sur votre patch.
Maintenant que tout est saisi, cliquez sur le bouton « Créer » pour soumettre votre patch.
Le fichier ainsi soumis disparaît de la section « Travaux en cours ». Le patch est maintenant disponible dans la section « Patch en attente de relecture » également présent dans la colonne de gauche de l’éditeur en ligne. En cliquant sur le titre, le contenu de la section s’affichera et votre patch y sera présent.
La communauté de PHP, et tout particulièrement la communauté française de PHP vous remercie pour votre aide.
Pour ma part, j’espère lire vos patchs ou vos commentaires prochainement.
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.
La documentation française de @official_php a besoin de vous ! Plus de 2300 fichiers à mettre à jour ou à traduire ! @afup R.T. S.V.P. pic.twitter.com/BS0Dag8vZa
— J. B. Nahan (@jbnahan69) 2 novembre 2017
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.
Mais qui regarde la doc en français ? 🤔
— Antoine Bellion (@antoinebellion) 2 novembre 2017
La réponse fut pertinente de la part de l’un des traducteurs de la documentation PHP :
les débutants avec un mauvais niveau en anglais 🙂
— Mehdi Achour (@mac_hour) 3 novembre 2017
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 ?
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 :
|
1 |
$ svn co https://svn.php.net/repository/phpdoc/modules/doc-fr |
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.
|
1 |
doc-fr$ git clone git clone http://git.php.net/repository/phd.git |
Il est possible de générer une première fois la documentation. Pour cela exécuter la commande configure suivante :
|
1 |
doc-fr$ php doc-base/configure.php --lang=fr |
Enfin, pour générer les pages HTML, exécuter la commande suivante :
|
1 |
doc-fr$ php phd/render.php --docbook doc-base/.manual.xml --package PHP --format xhtml --lang fr |
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.
|
1 |
doc-fr$ cd output/php-chunked-xhtml && php -S 0.0.0.0:8000 |
Ouvrez votre navigateur et saisir l’URL suivante http://127.0.0.1:8000
En continuant à utiliser le site, vous acceptez l'utilisation de cookies. Plus d'information
The cookie settings on this website are set to "allow cookies" to give you the best browsing experience possible. If you continue to use this website without changing your cookie settings or you click "Accept" below then you are consenting to this.