L’objectif de cet article est d’expliquer comment fonctionne la documentation de WordPress, comment la lire et où est-ce qu’elle se trouve (spoiler : pas dans le Codex !).

R.I.P. le vieux Codex… et Bonjour DevHub !

Le vénérable Codex WordPress n’est plus maintenu et il est maintenant en bonne partie obsolète. Cet outil a été abandonné depuis maintenant quelques années et ses pages redirigent progressivement vers DevHub, le site de la documentation de WordPress : developer.wordpress.org

Les redirections 301 sont mises en place au fur et à mesure de la migration du codex vers DevHub. Dans tous les cas, le Codex étant obsolète, il ne faut plus l’utiliser mais lui préférer les pages DevHub. De toutes manières, ce sont progressivement les pages DevHub qui remontent en premier sur Google.

À noter : cet article parle de la documentation technique de WordPress, nommée DevHub. Il existe également une documentation sur l’utilisation de WordPress, nommée HelpHub, mais c’est une toute autre plateforme, accessible à l’adresse fr.wordpress.org/support.

Comment lire la documentation sur developer.wordpress.org

Prenons par exemple une fonction de base de WordPress au hasard : get_the_time().

Sur la fiche developer.w.org, on retrouvera plusieurs sections :

Contribution : les User Contributed Notes

N’hésitez pas à proposer des user contributed notes ! Vous pouvez ajouter des commentaires concernant l’utilisation d’une fonction, ou des exemples d’usage avancé.

D’une part c’est un excellent moyen de contribuer à WordPress, d’autre part vous serez peut-être content de retrouver votre propre commentaire la prochaine fois que vous chercherez de la documentation sur cette fonction !

Les notes sont validées manuellement par l’équipe de documentation de WordPress. Si vous proposez une note, n’hésitez pas à me solliciter sur mon compte Twitter (ou sur le Slack WPFR) pour la valider vu que je m’occupe de leur modération 😃 Je fais généralement une passe de modération tous les 15 jours.

N’hésitez donc pas à prendre quelques dizaines de minutes pour proposer une user contributed note 🎖

Comment fonctionne la génération de la documentation de WordPress sur developer.w.org

La génération de la documentation des fonctions, classes, hooks, etc sur developer.wordpress.org est pour l’essentiel intégralement automatisée !

Cela fonctionne à l’aide de la syntaxe DocBlock, qui permet de définir la documentation d’un code source PHP sous la forme de blocs de commentaires. Ensuite, ces commentaires sont automatiquement scannés afin de générer la documentation de WordPress.

Back-office de developer.wordpress.org

Pour certaines fonctions, hooks ou classes particulièrement importantes, la génération de la documentation est semi-automatique : DocBlock permet de remonter une base de documentation et des contenus complémentaires sont ajoutés en back-office de dev.wordpress.org :

C’est par exemple le cas de la documentation de la classe WP_Query. Le type de contenu « Explanation » est alors utilisé pour ajouter des explications complémentaires.

Exemple de documentation d’une fonction WP

Si l’on reprend l’extemple de get_the_time(), voici les commentaires PHP qui se trouvent juste avant la fonction (située dans le fichier wp-includes/general-template.php) :

/**
 * Retrieve the time at which the post was written.
 *
 * @since 1.5.0
 *
 * @param string      $d    Optional. Format to use for retrieving the time the post
 *                          was written. Either 'G', 'U', or php date format defaults
 *                          to the value specified in the time_format option. Default empty.
 * @param int|WP_Post $post WP_Post object or ID. Default is global $post object.
 * @return string|int|false Formatted date string or Unix timestamp if `$d` is 'U' or 'G'. False on failure.
 */
function get_the_time( $d = '', $post = null ) {
    // Contenu de la fonction
}

La syntaxe DocBlock utilisée dans le cadre du logiciel WordPress est spécifiquement détaillée dans le handbook du Core WordPress.

À noter : il existe également une syntaxe de documentation spécifique à JavaScript.

Développeuses et développeurs : documentons le code que nous produisons !

Lors de la création d’une fonction, d’un hook ou d’une classe sur un thème ou sur une extension que nous avons créé, il est intéressant de documenter ce nouveau code en utilisant la syntaxe DocBlock. Il n’est pas strictement nécessaire d’utiliser l’ensemble des règles qui s’appliquent à WP mais au minimum, il est intéressant de les utiliser pour documenter :

Générer une documentation automatiquement avec WP à partir des commentaires DocBlock

Pour générer les pages de DevHub, une extension WordPress est utilisée sur WordPress.org. Cette extension scanne le cœur WP à la recherche de DocBlocks pour en créer la documentation. Pour chaque fonction, classe ou hook disposant d’un DocBlock, une page de documentation est automatiquement créée en utilisant les CPT que cette extension créée.

Rendu en back-office sur le site developer.wordpress.org :

Cette extension est open-source et installable sur n’importe quel site WP. Elle est disponible sur GitHub :

Je sais qu’elle est notamment utilisée par nos amis de Polylang pour générer leur documentation à destination des développeuses et des développeurs 😎