7.10. Hosting The Documentation On ReadTheDocs.org

First, you need to have a DVCS repository of your files accessible from Internet. ReadTheDocs.org supports currently Mercurial, Git, Subversion and Bazaar repositories. You can create your repository on sites such as Sourceforge.net.

When creating your branches in your repository, you should follow the Bugzilla project naming rules that is:

• Either name your branches or heads with the major number of the release, for instance 5.0
• Or tag your set of files with the major number of the release each time you modify your files and want to get it recompiled by RTD.org site

As an example, I already had a Mercurial repository to manage Bugzilla localization for the four supported branches and I used branch names like BUGZILLA_4_4 or BUGZILLA_5_0. So, each time I modify my localized files and I want them to be recompiled, I force the tag on my branch:

hg tag -f 5.0

ReadTheDocs.org site will get all the branch and tag names in your repository so you will only have to pick the right one in its interface.

Also, unless you host in your localized repository the Bugzilla source code, you will need to do the following: adding the file Constants.pm which is located in Bugzilla root directory and modifying your conf.py file:

|-- docs
|    |-- ab-CD
|       `--Constants.pm
|-- extensions
|-- template

I added it in the docs/ab-CD/ directory, but you can add it elsewhere. I would recommend you not to put it at the root of your localized files --that is to say at the same level as the docs/, extensions and template directories. If the user installs an old version of your localized tarball or if you forget to update this file, this will break Bugzilla by replacing the Constants.pm file provided by the Bugzilla source tarball. Then, the docsab-CDrstconf.py needs to be modified to reflect this change in the following section:

for line in open("../Constants.pm"):
    match = re.search(r'BUGZILLA_VERSION\s+=>\s+"([^"]+)"', line)
    if (match):
        release = match.group(1)
        match = re.search(r'^\d+\.\d+', release)
        if (match):
            version = match.group(0)
        else:
            version = release
        break

You will need to keep Constants.pm file in sync with the English version for each branch or head.

Then, get on ReadTheDocs.org site and create your account by clicking on the button Sign up. Fill up the form and click on the Sign Up » button:

Sign UP Form

On the page that appears, click on the Import a Project button:

Ready to share your documentation

Then, either connect to your GitHub or Bitbucket account or click on the Manually Import Project button

Note

Below will be detailed the manual way as I have not any account on GitHub or Bitbucket.

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 Edit advanced project options: square. Click then on the Next button:

Project Details

Fill now the new form, especially the Description, Documentation and Language fields. The other fields can be ignored and modified later if necessary. Then, click on the Finish button:

Project Extra Details

Now, click on the Versions button in the navigation header and in the Inactive Versions section, choose the version you want to activate by clicking on the Edit button:

Versions

Inactive versions

Tick the Active: square and click on the Save button:

Editing Version

Now, click on the Overview button in the navigation header. The version you have just made active should appear there. In the Build a version dropdown list, select the version you want to compile and click on the Build button to compile your localized documentation:

Overview

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.

---

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