7.8. Compiling The DocumentationΒΆ

To compile the documentation, you need the Sphinx software and the rst2pdf tool. You should have both already if you followed the installation process.

Note

PDF generation does not work currently with python3-sphinx package.

You can test that you are able to compile the docs by running the following command in the docs/ directory:

./makedocs.pl

This will generate the English documentation files in HTML, PDF and plain text formats in the docs/en directory and its subdirectories.

If all is running fine, you can then copy your localized directory in the docs/ directory. You should have then three directories:

You should now customize the file docs/ab-CD/rst/conf.py. Here are the sections you should edit:

# 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>`_.
"""

For this last section, pay attention to the letter u added before the three double quotes: it is not present in the English version of this file. This letter indicates that the text following will contain non-ASCII characters and your language will probably needs non-ASCII characters. If you omit to add this letter and that your localization contains non-ASCII characters, the compilation of the documentation will not work. The multiple dashes are here for formatting purposes and will render as a line in the HTML version.

Another section you will want to edit is the following one:

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

If your locale is available for Sphinx (to find out, consult the Sphinx documentation) then you should uncomment the line and specify your locale code here:

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

If your locale is not available for Sphinx, then the labels for navigation elements -- next, previous, search box, etc. -- will not be localized.