<div dir="ltr">On 31 August 2013 14:35, Gervase Markham <span dir="ltr"><<a href="mailto:gerv@mozilla.org" target="_blank">gerv@mozilla.org</a>></span> wrote:<br><div class="gmail_extra"><div class="gmail_quote"><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">

Hi everyone,<br>
<br>
Further to pervious emails on the subject, I've hacked up something to<br>
convert the Bugzilla docs from Docbook to RST (ReStructured Text),<br>
uploaded them to Github and connected the Github repo to <a href="http://readthedocs.org" target="_blank">readthedocs.org</a>.<br>
<br>
I'm sure there are style and conversion nits, but I think it's good<br>
enough to evaluate whether this is the way we want to go.<br>
<br>
The advantages of this system is that RST is much easier to edit, Sphinx<br>
can be installed locally (as one package) so that anyone hacking on the<br>
docs can compile them themselves to HTML or other formats, and<br>
<a href="http://readthedocs.org" target="_blank">readthedocs.org</a> automatically takes care of making sure we have a lovely<br>
web version. Because it's SCM-backed, we can have branches for each<br>
version of Bugzilla, which was a requirement. And if and when Bugzilla<br>
moves to Git, I'm pretty sure we can then simply keep the docs in the<br>
same repo as the code.<br>
<br>
Comments?<br></blockquote><div><br></div><div>I think this seems like quite a good idea, to be honest...</div><div><br></div><div>I did find a more up-to-date db2rst script at <a href="https://github.com/kurtmckee/db2rst">https://github.com/kurtmckee/db2rst</a> which might help? I've not tried it as I'm not sure what changes you'd made in the first place.</div>
<div><br></div><div>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 :-)</div><div><br>
</div><div>Colin </div></div></div></div>