7.9. Compiling The Documentation

To compile the documentation, you need to install the Sphinx software and at least the tool to convert .rst files into .pdf files:

sudo apt-get install python-sphinx rst2pdf

You can alternatively install TeX packages instead of rst2pdf, but they will take lots of space on your hard disk. If you still want to do so, run the following command:

sudo apt-get install python-sphinx texlive-latex-base texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended

Note

PDF generation does not work currently with python3-sphinx package.</p>

Another Perl module is needed by the docs/makedocs.pl script to launch the compilation:

File::Which

Run the following command to install it:

sudo apt-get install libfile-which-perl

Now, you can test that your installation is functional 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:

Where ab-CD is your locale code.

You should now customized the file docs/ab-CD/rst/conf.py. Here are the section you should take care of:

# 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'),
]

You can localize what is hightlighted above in green.

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 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 certainly 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 purpose and will render as a line in the HTML version.

Another section you would 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

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'

For a list of available locales, you can consult Sphinx documentation.

If your locale is not present, then the different labels for navigation --next, previous, search box, etc.-- will not be localized. If this is the case, let this line commented; these words will be then displayed in English.

---

This documentation undoubtedly has bugs; if you find some, please file them here.