Docs now converted to RST and up on ReadTheDocs

classic Classic list List threaded Threaded
5 messages Options
Reply | Threaded
Open this post in threaded view
|

Docs now converted to RST and up on ReadTheDocs

Gervase Markham
I've just checked in the fix for bug 912064:
https://bugzilla.mozilla.org/show_bug.cgi?id=912064
and so Bugzilla's documentation format is now RST (ReStructured Text)
rather than XML DocBook.

We hope that this will make the docs much easier to edit and contribute
to (although building the PDF version still requires 1GB of TeX...).

It also means we can put them up on ReadTheDocs, and I have now done so:

http://bugzilla.readthedocs.org/en/latest/

Pretty! :-)

There are many things still to do, but this is a good base for moving
forwards. I will be filing more bugs about enhancements, and encourage
others to do the same. Soon, we will perhaps want to reorganize the
docs, import a load of stuff which has up to now lived in the wiki
(because changing the docs was too hard) and so on.

Gerv
_______________________________________________
dev-apps-bugzilla mailing list
[hidden email]
https://lists.mozilla.org/listinfo/dev-apps-bugzilla
-
To view or change your list settings, click here:
<http://bugzilla.org/cgi-bin/mj_wwwusr?user=lists+s6506n84121h51@...>
Reply | Threaded
Open this post in threaded view
|

Re: Docs now converted to RST and up on ReadTheDocs

Cédric Corazza
Le 17/01/2014 11:52, Gervase Markham a écrit :

> I've just checked in the fix for bug 912064:
> https://bugzilla.mozilla.org/show_bug.cgi?id=912064
> and so Bugzilla's documentation format is now RST (ReStructured Text)
> rather than XML DocBook.
>
> We hope that this will make the docs much easier to edit and contribute
> to (although building the PDF version still requires 1GB of TeX...).
>
> It also means we can put them up on ReadTheDocs, and I have now done so:
>
> http://bugzilla.readthedocs.org/en/latest/
>
> Pretty! :-)
>
> There are many things still to do, but this is a good base for moving
> forwards. I will be filing more bugs about enhancements, and encourage
> others to do the same. Soon, we will perhaps want to reorganize the
> docs, import a load of stuff which has up to now lived in the wiki
> (because changing the docs was too hard) and so on.
>
> Gerv
>
Hi,

I'm the French localizer of Bugzilla
(http://frenchmozilla.cvs.sourceforge.net/viewvc/frenchmozilla/bugzilla/?pathrev=HEAD)
Reading bug 912064, I can't see how to convert the current French files
to the new system and link them to https://bugzilla.readthedocs.org/.
Is there an how-to file somewhere to explain this?
This might interest as well the other localizers
(http://www.bugzilla.org/download/#localizations).
Thanks.

Cédric
_______________________________________________
dev-apps-bugzilla mailing list
[hidden email]
https://lists.mozilla.org/listinfo/dev-apps-bugzilla
-
To view or change your list settings, click here:
<http://bugzilla.org/cgi-bin/mj_wwwusr?user=$MSGRCPT>
Reply | Threaded
Open this post in threaded view
|

Re: Docs now converted to RST and up on ReadTheDocs

Gervase Markham
On 17/01/14 11:03, Cédric Corazza wrote:
> I'm the French localizer of Bugzilla
> (http://frenchmozilla.cvs.sourceforge.net/viewvc/frenchmozilla/bugzilla/?pathrev=HEAD)
>
> Reading bug 912064, I can't see how to convert the current French files
> to the new system and link them to https://bugzilla.readthedocs.org/.
> Is there an how-to file somewhere to explain this?
> This might interest as well the other localizers
> (http://www.bugzilla.org/download/#localizations).

That's a very good question.

Converting them to the new system: one option is to use the db2rst.py
and makebzdocs tools here, which I used to do the initial conversion:
https://github.com/gerv/bzdocs

There's then quite a bit of fixup to do, which I did manually. I'm
afraid I didn't keep records of exactly what I did :-( The other option
is to take the new English docs and copy-paste each para of French into
the structure, but that might be more work.

As for putting them on ReadTheDocs, there's a FAQ answer:

https://docs.readthedocs.org/en/latest/faq.html#how-do-i-support-multiple-languages-of-documentation

They want to have full language support, but it's not there yet.
(Patches welcome? :-) In the mean time, the FAQ suggests creating a
project for each language of documentation. So we would have:

bugzilla-fr.readthedocs.org
bugzilla-de.readthedocs.org

etc. and point each of them at the place where you keep your translation
of the docs. Although RTD doesn't support CVS - only Git, SVN, BZR and
Hg - so you'd need to move the Bugzilla docs somewhere else, or use
Subversion SVN.

I note that we only have very old non-English versions of docs linked
from http://www.bugzilla.org/docs/ . You should file a bug in
Bugzilla::bugzilla.org to get that fixed.

Gerv

_______________________________________________
dev-apps-bugzilla mailing list
[hidden email]
https://lists.mozilla.org/listinfo/dev-apps-bugzilla
-
To view or change your list settings, click here:
<http://bugzilla.org/cgi-bin/mj_wwwusr?user=$MSGRCPT>
Reply | Threaded
Open this post in threaded view
|

Re: Docs now converted to RST and up on ReadTheDocs

Cédric Corazza
Le 17/01/2014 13:00, Gervase Markham a écrit :
> Converting them to the new system: one option is to use the db2rst.py
> and makebzdocs tools here, which I used to do the initial conversion:
> https://github.com/gerv/bzdocs
>
> There's then quite a bit of fixup to do, which I did manually. I'm
> afraid I didn't keep records of exactly what I did :-( The other option
> is to take the new English docs and copy-paste each para of French into
> the structure, but that might be more work.


I succeeded to convert the French documentation files almost flawlessly
in an afternoon with the script on your repository. I just have now to
get used to the RST syntax and fix some little remaining syntax errors.
Will blog about this tomorrow with the link to the fr Documentation.

> As for putting them on ReadTheDocs, there's a FAQ answer:
>
> https://docs.readthedocs.org/en/latest/faq.html#how-do-i-support-multiple-languages-of-documentation
>
> They want to have full language support, but it's not there yet.
> (Patches welcome? :-) In the mean time, the FAQ suggests creating a
> project for each language of documentation. So we would have:
>
> bugzilla-fr.readthedocs.org
> bugzilla-de.readthedocs.org
>
> etc. and point each of them at the place where you keep your translation
> of the docs. Although RTD doesn't support CVS - only Git, SVN, BZR and
> Hg - so you'd need to move the Bugzilla docs somewhere else, or use
> Subversion SVN.

I migrated my CVS repository to Mercurial and will look at the FAQ on RTD.

> I note that we only have very old non-English versions of docs linked
> from http://www.bugzilla.org/docs/ . You should file a bug in
> Bugzilla::bugzilla.org to get that fixed.

I didn't notice that page. I will file a bug after hosting the
up-to-date localized doc on my site. Probably tomorrow.

Cédric

_______________________________________________
dev-apps-bugzilla mailing list
[hidden email]
https://lists.mozilla.org/listinfo/dev-apps-bugzilla
-
To view or change your list settings, click here:
<http://bugzilla.org/cgi-bin/mj_wwwusr?user=$MSGRCPT>
Reply | Threaded
Open this post in threaded view
|

Re: Docs now converted to RST and up on ReadTheDocs

Frédéric Buclin
In reply to this post by Gervase Markham
Le 17. 01. 14 11:52, Gervase Markham a écrit :
> We hope that this will make the docs much easier to edit and contribute
> to (although building the PDF version still requires 1GB of TeX...).

Bug 961398 lets you build the PDF doc using rst2pdf instead of pdflatex.
So instead of 1.1Gb, you only need a few Mb.


LpSolit

-
To view or change your list settings, click here:
<http://bugzilla.org/cgi-bin/mj_wwwusr?user=lists+s6506n84121h51@...>