diff options
Diffstat (limited to 'docs/en/rst/localizing/compiling-documentation.rst')
| -rw-r--r-- | docs/en/rst/localizing/compiling-documentation.rst | 112 |
1 files changed, 112 insertions, 0 deletions
diff --git a/docs/en/rst/localizing/compiling-documentation.rst b/docs/en/rst/localizing/compiling-documentation.rst new file mode 100644 index 000000000..06f61709f --- /dev/null +++ b/docs/en/rst/localizing/compiling-documentation.rst @@ -0,0 +1,112 @@ +.. _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 <https://bugzilla.mozilla.org/enter_bug.cgi?product=Bugzilla&component=Documentation>`_.</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. + + + |