7.8. Compilation de la documentation

Pour compiler la documentation, vous avez besoin du logiciel Sphinx et de l'outil rst2pdf. Vous devriez déjà avoir ceux-ci installés si vous avez suivi la procédure d'installation.

Note

La génération PDF ne fonctionne pas pour le moment avec le paquet python3-sphinx.

Vous pouvez tester que vous êtes en mesure de compiler la documentation en exécutant la commande suivante dans le répertoire docs/ :

./makedocs.pl

Ceci générera la documentation anglaise en HTML, en PDF et en texte brut dans le répertoire docs/en et ses sous-répertoires.

Si tout se passe bien, vous pouvez alors copier votre répertoire localisé dans le répertoire docs/. Vous devriez alors avoir les trois répertoires suivants :

Vous devez maintenant personnaliser le fichier docs/ab-CD/rst/conf.py. Voici les sections que vous devez modifier :

# General information about the project.
project = u'Bugzilla'
copyright = u'2014, The Bugzilla Team'

latex_documents = [
  ('index', 'Bugzilla.tex', u'Bugzilla Documentation',
   u'The Bugzilla Team', 'manual'),
]

man_pages = [
    ('index', 'bugzilla', u'Bugzilla Documentation',
     [u'The Bugzilla Team'], 1)
]

texinfo_documents = [
  ('index', 'Bugzilla', u'Bugzilla Documentation',
   u'The Bugzilla Team', 'Bugzilla', 'One line description of project.',
   'Miscellaneous'),
]

pdf_documents = [
('index', u'Bugzilla', u'Bugzilla Documentation', u'The Bugzilla Team'),
]

rst_epilog = u"""

----------

This documentation undoubtedly has bugs; if you find some, please file
them `here <https://bugzilla.mozilla.org/enter_bug.cgi?product=Bugzilla&component=Documentation>`_.
"""

Pour cette dernière section, notez bien la lettre u ajoutée devant les trois guillemets doubles : elle n'est pas présente dans la version anglaise de ce fichier. Cette lettre indique que le texte qui suit contient des caractères non-ASCII et votre langue en aura probablement besoin. Si vous omettez d'ajouter cette lettre et que votre localisation contient des caractères non-ASCII, la compilation de la documentation échouera. Les multiples tirets servent ici pour le formatage et seront affichés sous la forme d'une ligne dans la version HTML.

Une autre section que vous voudrez éditer est la suivante :

# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#language = None

Si votre locale est disponible dans Sphinx (pour le savoir, consulter la documentation Sphinx) vous pouvez enlever le commentaire de la ligne et indiquer le code de votre locale ici :

# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
language = 'fr'

Si votre locale n'est pas disponible dans Sphinx, alors les libellés pour les éléments de navigation -- suivant, précédent, boîte de recherche, etc. -- ne seront pas localisés.