Bugzilla docs: test conversion to RST and hosting on readthedocs.org

[Gervase Markham]

Hi everyone,

Further to pervious emails on the subject, I've hacked up something to
convert the Bugzilla docs from Docbook to RST (ReStructured Text),
uploaded them to Github and connected the Github repo to readthedocs.org.

It's hackily done, and one thing that hasn't come across is the TOC
(which is auto-generated when using Docbook). So there isn't an index
page. But you can see the results here:

https://bugzilla.readthedocs.org/en/latest/about.html
https://bugzilla.readthedocs.org/en/latest/administration.html
https://bugzilla.readthedocs.org/en/latest/Bugzilla-Guide.html
https://bugzilla.readthedocs.org/en/latest/conventions.html
https://bugzilla.readthedocs.org/en/latest/customization.html
https://bugzilla.readthedocs.org/en/latest/gfdl.html
https://bugzilla.readthedocs.org/en/latest/glossary.html
https://bugzilla.readthedocs.org/en/latest/installation.html
https://bugzilla.readthedocs.org/en/latest/modules.html
https://bugzilla.readthedocs.org/en/latest/patches.html
https://bugzilla.readthedocs.org/en/latest/security.html
https://bugzilla.readthedocs.org/en/latest/troubleshooting.html
https://bugzilla.readthedocs.org/en/latest/using.html

I'm sure there are style and conversion nits, but I think it's good
enough to evaluate whether this is the way we want to go.

The advantages of this system is that RST is much easier to edit, Sphinx
can be installed locally (as one package) so that anyone hacking on the
docs can compile them themselves to HTML or other formats, and
readthedocs.org automatically takes care of making sure we have a lovely
web version. Because it's SCM-backed, we can have branches for each
version of Bugzilla, which was a requirement. And if and when Bugzilla
moves to Git, I'm pretty sure we can then simply keep the docs in the
same repo as the code.

Comments?

Gerv
_______________________________________________
dev-apps-bugzilla mailing list
dev-apps-bugzilla at lists.mozilla.org
https://lists.mozilla.org/listinfo/dev-apps-bugzilla