7.10. Hébergement de la documentation sur readthedocs.org

Vous voudrez peut-être rendre vos modèles et votre documentation disponibles dans dans une archives pour être installés. Cependant, la documentation principale de Bugzilla est hébergée sur le site readthedocs.org. If you put your localized documentation up on that site, then it can be linked in with the main Bugzilla docs and appear as an alternative version.

Pour cela, vous devrez disposer d'un dépôt DVCS de vos fichiers accessibles d'Internet. ReadTheDocs.org sait actuellement gérer des dépôts Mercurial, Git, Subversion et Bazaar, mais si vous travaillez sur un clone du dépôt principal de Bugzilla, vous devez utiliser Git. Vous pouvez créer votre dépôt sur des sites comme Github ou sourceforge.net. Il est plus facile de publier toute l'arborescence de code, y compris le code source de Bugzilla, car certaines parties de ce code sont nécessaires pour compiler la documentation.

Vous devez utiliser des branches ou des têtes libellées d'après le nom des versions majeures de Bugzilla, par exemple 5.0. Si vous utilisez votre propre dépôt plutôt qu'un clone Git de Bugzilla, vous devez également nommer vos branches de cette manière.

Ensuite, rendez-vous sur le site readthedocs.org et créez un compte en cliquant sur le bouton Sign up. Remplissez le formulaire et cliquez sur le bouton Sign Up » :

../_images/RTD1.png

Sign Up Form

Sur la page qui apparaît, cliquez sur le bouton Import a Project :

../_images/RTD2.png

Ready to share your documentation

Ensuite, connectez-vous à votre compte GitHub ou cliquez sur le bouton Manually Import Project. L'importation manuelle sera expliquée ci-dessous.

../_images/RTD3.png

Import a Project

Vous devez maintenant nommer votre projet en suivant la règle de nommage suivante : bugzilla-ab-CD --où ab-CD est votre code de locale--, spécifier l'URL de votre dépôt et son type, puis cocher la case Edit advanced project options:. Cliquez alors sur le bouton Next :

../_images/RTD4.png

Project Details

Remplissez le nouveau formulaire, et plus particulièrement les champs Description, Documentation et Language. Les autres champs peuvent être ignorés et modifiés plus tard si nécessaire. Cliquez alors sur le bouton Finish :

../_images/RTD5.png

Project Extra Details

Cliquez à présent sur le bouton Versions dans l'en-tête de navigation et dans la section Inactive Versions, choisissez la version que vous voulez activer en cliquant sur le bouton Edit :

../_images/RTD6.png

Versions

../_images/RTD7.png

Inactive versions

Cochez la case Active: et cliquez sur le bouton Save :

../_images/RTD8.png

Editing Version

Cliquez à présent sur le bouton Overview dans l'en-tête de navigation. La version que vous venez d'activer devrait y apparaître. Dans la liste déroulante Build a version, sélectionnez la version que vous voulez compiler et cliquez sur le bouton Build pour compiler votre documentation localisée :

../_images/RTD9.png

Overview

../_images/RTD10.png

Compilation Results

Si le résultat est Passed, votre compilation a été compilée avec succès. Si le résultat est Failed, cliquez sur le lien pour voir ce qui s'est mal passé et corrigez-le.

Enfin, informez le projet Bugzilla que la documentation est prête dans votre langue en envoyant un courriel sur la liste de diffusion developers AT bugzilla.org en indiquant le nom du projet, c'est à dire bugzilla-ab-CD. Ils pourront alors lier votre documentation à la documentation principale pour qu'elle puisse être affichée en langue alternative.