<html><head></head><body>Sounds like a plan. I like it.<br><br><div class="gmail_quote">Gervase Markham <gerv@mozilla.org> wrote:<blockquote class="gmail_quote" style="margin: 0pt 0pt 0pt 0.8ex; border-left: 1px solid rgb(204, 204, 204); padding-left: 1ex;">
<pre class="k9mail">On 31/08/13 14:35, Gervase Markham wrote:<br /><blockquote class="gmail_quote" style="margin: 0pt 0pt 1ex 0.8ex; border-left: 1px solid #729fcf; padding-left: 1ex;">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">readthedocs.org</a>.</blockquote><br />Anyone other than Colin have comments here?<br /><br />If we think this is the right way to go, I think we should:<br /><br />- Convert the trunk docs (only) in a one-off process<br /><br />- Patch them up so we have a TOC etc. (the conversion is not 100%<br />perfect)<br /><br />- rewrite <a href="http://makedocs.pl">makedocs.pl</a> to use Sphinx to build HTML, LaTeX -> PDF, and TXT<br />(if the relevant converters are available)<br /><br />- Check this all in on trunk, using the directory docs/en/rst, and<br />remove
the XML
versions and checked-in built versions<br /><br />- Point <a href="http://bugzilla.readthedocs.org">http://bugzilla.readthedocs.org</a> at the trunk repo (RTD<br />supports Bazaar, so we don't have to wait for any SCM shift)<br /><br />- (Optional) Add a post-commit hook to ping RTD to rebuild on checkin<br /><br />- Update the "HTML" and "PDF" links on <a href="http://www.bugzilla.org/docs">http://www.bugzilla.org/docs</a>/ to<br />point to RTD; retain the "API" link; eliminate the "TXT" link<br /><br />If this sounds like a plan, I'll file some bugs.<br /><br />Gerv<br /><br /><blockquote class="gmail_quote" style="margin: 0pt 0pt 1ex 0.8ex; border-left: 1px solid #729fcf; padding-left: 1ex;">It's hackily done, and one thing that hasn't come across is the TOC<br />(which is auto-generated when using Docbook). So there isn't an index<br />page. But you can see the results here:<br /><br /><a
href="https://bugzilla.readthedocs.org/en/latest/about.html">https://bugzilla.readthedocs.org/en/latest/about.html</a><br /><a href="https://bugzilla.readthedocs.org/en/latest/administration.html">https://bugzilla.readthedocs.org/en/latest/administration.html</a><br /><a href="https://bugzilla.readthedocs.org/en/latest/Bugzilla-Guide.html">https://bugzilla.readthedocs.org/en/latest/Bugzilla-Guide.html</a><br /><a href="https://bugzilla.readthedocs.org/en/latest/conventions.html">https://bugzilla.readthedocs.org/en/latest/conventions.html</a><br /><a href="https://bugzilla.readthedocs.org/en/latest/customization.html">https://bugzilla.readthedocs.org/en/latest/customization.html</a><br /><a href="https://bugzilla.readthedocs.org/en/latest/gfdl.html">https://bugzilla.readthedocs.org/en/latest/gfdl.html</a><br /><a href="https://bugzilla.readthedocs.org/en/latest/glossary.html">https://bugzilla.readthedocs.org/en/latest/glossary.html</a><br /><a
href="https://bugzilla.readthedocs.org/en/latest/installation.html">https://bugzilla.readthedocs.org/en/latest/installation.html</a><br /><a href="https://bugzilla.readthedocs.org/en/latest/modules.html">https://bugzilla.readthedocs.org/en/latest/modules.html</a><br /><a href="https://bugzilla.readthedocs.org/en/latest/patches.html">https://bugzilla.readthedocs.org/en/latest/patches.html</a><br /><a href="https://bugzilla.readthedocs.org/en/latest/security.html">https://bugzilla.readthedocs.org/en/latest/security.html</a><br /><a href="https://bugzilla.readthedocs.org/en/latest/troubleshooting.html">https://bugzilla.readthedocs.org/en/latest/troubleshooting.html</a><br /><a href="https://bugzilla.readthedocs.org/en/latest/using.html">https://bugzilla.readthedocs.org/en/latest/using.html</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 th
at 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">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 /><br />Gerv<br /><hr /><br />dev-apps-bugzilla mailing list<br />dev-apps-bugzilla@lists.mozilla.org<br /><a href="https://lists.mozilla.org/listinfo/dev-apps-bugzilla">https://lists.mozilla.org/listinfo/dev-apps-bugzilla</a><br />-<br />To view or change your list settings, click here:<br /><<a
href="http://bugzilla.org/cgi-bin/mj_wwwusr?user=gerv@mozilla.org">http://bugzilla.org/cgi-bin/mj_wwwusr?user=gerv@mozilla.org</a>></blockquote><br />-<br />To view or change your list settings, click here:<br /><<a href="http://bugzilla.org/cgi-bin/mj_wwwusr?user=justdave@bugzilla.org">http://bugzilla.org/cgi-bin/mj_wwwusr?user=justdave@bugzilla.org</a>><br /></pre></blockquote></div><br>
-- <br>
Sent from my Android phone with K-9 Mail. Please excuse my brevity.</body></html>