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/hosting-documentation.rst | 96 ++++++++++++++++++++++++
 1 file changed, 96 insertions(+)
 create mode 100644 docs/en/rst/localizing/hosting-documentation.rst

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

diff --git a/docs/en/rst/localizing/hosting-documentation.rst b/docs/en/rst/localizing/hosting-documentation.rst
new file mode 100644
index 000000000..0bf4e8df8
--- /dev/null
+++ b/docs/en/rst/localizing/hosting-documentation.rst
@@ -0,0 +1,96 @@
+.. _hosting-documentation:
+
+Hosting The Documentation On readthedocs.org
+############################################
+
+You will want to make your templates and documentation available in a
+localization tarball for sites to install. However, Bugzilla's main
+documentation site is readthedocs.org. If you put your localized documentation
+up on that site, then it can be linked in with the main Bugzilla docs and
+appear as an alternative version.
+
+To do this, you need to have a
+`DVCS <https://en.wikipedia.org/wiki/Distributed_revision_control>`_ repository
+of your files accessible from the Internet. ReadTheDocs.org currently supports
+Mercurial, Git, Subversion and Bazaar repositories, but if you are working in
+a clone of the main Bugzilla repo, you will be using Git.
+You can create your repository on sites such as
+`Github <https://github.com/>`_ or `sourceforge.net <https://sourceforge.net/>`_.
+It is both easiest and best if you publish your entire code tree, including the
+Bugzilla source code, as some of it is needed to compile the docs.
+
+You should localize on the branch or head named after the major number of the
+release, for instance '``5.0``'. If you are making your own repo rather than
+cloning the Bugzilla one, you should name your branches in this way also.
+
+Then, get on the `readthedocs.org <https://readthedocs.org>`_ site and create
+an account by clicking on the button :guilabel:`Sign up`. Fill up the form and
+click on the :guilabel:`Sign Up »` button:
+
+.. image:: ../../images/RTD1.png
+
+*Sign Up Form*
+
+On the page that appears, click on the :guilabel:`Import a Project` button:
+
+.. image:: ../../images/RTD2.png
+
+*Ready to share your documentation*
+
+Then, either connect to your GitHub account or click on the :guilabel:`Manually Import Project`
+button. The manual way will be explained below.
+
+.. image:: ../../images/RTD3.png
+
+*Import a Project*
+
+You should now name your project, following the naming rule ``bugzilla-ab-CD`` --where ab-CD is your locale code--,
+specify the URL for your repository and its type, and tick the :guilabel:`Edit advanced project options:` square. Click then
+on the :guilabel:`Next` button:
+
+.. image:: ../../images/RTD4.png
+
+*Project Details*
+
+Fill now the new form, especially the :guilabel:`Description`, :guilabel:`Documentation` and :guilabel:`Language` fields. The other
+fields can be ignored and modified later if necessary. Then, click on the :guilabel:`Finish` button:
+
+.. image:: ../../images/RTD5.png
+
+*Project Extra Details*
+
+Now, click on the :guilabel:`Versions` button in the navigation header and in the :guilabel:`Inactive Versions` section, choose
+the version you want to activate by clicking on the :guilabel:`Edit` button:
+
+.. image:: ../../images/RTD6.png
+
+*Versions*
+
+.. image:: ../../images/RTD7.png
+
+*Inactive versions*
+
+Tick the :guilabel:`Active:` square and click on the :guilabel:`Save` button:
+
+.. image:: ../../images/RTD8.png
+
+*Editing Version*
+
+Now, click on the :guilabel:`Overview` button in the navigation header. The version you have just made active should appear there.
+In the :guilabel:`Build a version` dropdown list, select the version you want to compile and click on the :guilabel:`Build` button to compile
+your localized documentation:
+
+.. image:: ../../images/RTD9.png
+
+*Overview*
+
+.. image:: ../../images/RTD10.png
+
+*Compilation Results*
+
+If the result is ``Passed``, your documentation has been successfully compiled. If the result is ``Failed``, click
+on the link to see what went wrong and fix it.
+
+Finally, you should inform the Bugzilla Project that the documentation is ready in your language by sending a mail to
+the mailing-list ``developers AT bugzilla.org`` giving your project name, that is ``bugzilla-ab-CD``. They can
+then link your docs into the main Bugzilla docs so that they show up as an alternative language.
-- 
cgit v1.2.3-24-g4f1b