.. _compiling-documentation:

Compiling The Documentation
###########################

To compile the documentation, you need the Sphinx software and the :command:`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 :file:`docs/` directory:

:command:`./makedocs.pl`

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

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

.. code-block: text

  |-- docs
  |    |-- ab-CD
  |    |-- en
  |    |-- lib

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

.. raw:: html

  <pre>
  # General information about the project.
  project = u'<mark>Bugzilla</mark>'
  copyright = u'<mark>2014, The Bugzilla Team</mark>'
  </pre>

.. raw:: html

  <pre>latex_documents = [
    ('index', 'Bugzilla.tex', u'<mark>Bugzilla Documentation</mark>',
     u'<mark>The Bugzilla Team</mark>', 'manual'),
  ]
  </pre>

.. raw:: html

  <pre>
  man_pages = [
      ('index', 'bugzilla', u'<mark>Bugzilla Documentation</mark>',
       [u'<mark>The Bugzilla Team</mark>'], 1)
  ]
  </pre>

.. raw:: html

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

.. raw:: html

  <pre>
  pdf_documents = [
  ('index', u'<mark>Bugzilla</mark>', u'<mark>Bugzilla Documentation</mark>', u'<mark>The Bugzilla Team</mark>'),
  ]
  </pre>

.. raw:: html

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

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:

.. code-block:: text

  # 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 <http://sphinx-doc.org/config.html#confval-language>`_)
then you should uncomment the line and specify your locale code here:

.. raw:: html

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

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