From 7321534b42aab3ab2064c73b6326d52f395f023c Mon Sep 17 00:00:00 2001
From: Gervase Markham <gerv@gerv.net>
Date: Wed, 30 Sep 2015 09:03:22 +0100
Subject: Bug 1156785 - add new Localization Guide for in-place review.

---
 docs/en/rst/localizing/compiling-documentation.rst | 112 +++++++++++++++++++++
 1 file changed, 112 insertions(+)
 create mode 100644 docs/en/rst/localizing/compiling-documentation.rst

(limited to 'docs/en/rst/localizing/compiling-documentation.rst')

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 &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.
+
+
+
-- 
cgit v1.2.3-24-g4f1b