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

[Colin Ogilvie]

On 31 August 2013 14:35, Gervase Markham <gerv at mozilla.org> wrote:

> 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.
>
> 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?
>

I think this seems like quite a good idea, to be honest...

I did find a more up-to-date db2rst script at
https://github.com/kurtmckee/db2rst which might help? I've not tried it as
I'm not sure what changes you'd made in the first place.

The index issue: we could probably hard-code the generation of the list, or
at least work on a sort order... a quick 5 minute play has got me
generating an index, but it's not ideal :-)

Colin
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.bugzilla.org/pipermail/developers/attachments/20130831/c026e720/attachment.html>