Écriture de la documentation de Bugzilla

La documentation de Bugzilla utilise reStructured Text (reST), étendu par notre outil de compilation de documentation, Sphinx. Ce document est sous format reST à des fin de démonstration seulement. Quand vous réalisez les documents, il est construit (au moins dans la version HTML) comme un seul fichier, bien qu’il ne soit pas lisible sous cette forme car certaines des directives sont invisibles ou changent lors du rendu du document.

La documentation de Sphinx donne une bonne introduction à reST et aux extensions spécifiques à Sphinx. Lire cette page devrait suffire pour démarrer. Ensuite, la section inline markup vaut la peine d’être lue.

Les conventions particulières de la documentation de Bugzilla sont les suivantes :

Directives de blocs

Chaque titre doit être précédé par une ancre, avec un nom unique pour tout le document et sans espace. Ensuite, nous décrirons les niveaux de titres disponibles que nous n’avons pas encore utilisés :

Premier niveau de titre

Quatrième niveau de titre

Cinquième niveau de titre

(Essayer de ne pas utiliser des niveaux de titres allant jusqu’au 5e niveau).

Les liens vers les ancres se construisent ainsi : Premier niveau de titre. Il utilisera alors le titre qui suit et l’utilisera comme libellé du lien. N’utilisez pas les liens standard internes de reST comme : nomdancreunique - ils ne fonctionneront pas entre plusieurs fichiers.

Les commentaires sont réalisés comme ceci :

Autres types de bloc :

Note

Ceci est une note, pour votre information. Comme tous les blocs avec deux points (..), les lignes qui suivent doivent être indentées.

Avertissement

Ceci est un avertissement pour un problème potentiel dont vous devez être conscient.

Utilisez les deux types de blocs ci-dessus avec modération. Considérez de mettre l’information dans le texte principal, omettez-la, ou, si elle est longue, placez-la dans un fichier subsidiaire.

Les sections de code sont mises en valeur en utilisant Pygments. Choisissez la mise en valeur en haut de chaque fichier en utilisant :

Vous pouvez changer la mise en valeur pour un bloc particulier en l’introduisant comme ceci avant le bloc concerné :

# Ceci est du code Perl
print "Bonjour";

Il existe une liste de tous les noms de lexer disponibles. Nous utilisons actuellement console, perl et sql. none est aussi une valeur valide.

Utiliser 4 espaces pour les indentation, sauf quand une valeur différente est plus adaptée pour que ce soit aligné. Donc deux espaces pour les listes à puces et trois espaces pour les .. blocs.

Directives inline

Avertissement

Souvenez-vous que reST ne sait pas gérer le balisage indenté. Vous ne pouvez donc avoir de substitution à l’intérieur d’un lien ou une mise en caractères gras à l’intérieur d’un texte en italiques.

  • Un nom de fichier ou un chemin vers un fichier est construit comme suit : /path/to/filename.ext

  • Une commande à saisir dans la console est construite comme ceci : commande --arguments

  • Un nom de paramètre : shutdownhtml

  • Une valeur de paramètre : DB

  • Un nom de groupe : editbugs

  • Un champ de bogue : Résumé

  • Toute chaîne de l’interface graphique : Administration

  • Un bogue spécifique dans bugzilla.mozilla.org : bug 201069

Cette documentation contient très probablement des bogues ; si vous en découvrez, veuillez les signaler ici.