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

[Mark Côté]

I too love this. Another step in modernizing Bugzilla! :)

Mark


On 2013-09-03 6:36 AM, Gervase Markham wrote:
> On 31/08/13 14:35, Gervase Markham wrote:
>> 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.
> Anyone other than Colin have comments here?
>
> If we think this is the right way to go, I think we should:
>
> - Convert the trunk docs (only) in a one-off process
>
> - Patch them up so we have a TOC etc. (the conversion is not 100%
>   perfect)
>
> - rewrite makedocs.pl to use Sphinx to build HTML, LaTeX -> PDF, and TXT
>   (if the relevant converters are available)
>
> - Check this all in on trunk, using the directory docs/en/rst, and
>   remove the XML versions and checked-in built versions
>
> - Point http://bugzilla.readthedocs.org at the trunk repo (RTD
>   supports Bazaar, so we don't have to wait for any SCM shift)
>
> - (Optional) Add a post-commit hook to ping RTD to rebuild on checkin
>
> - Update the "HTML" and "PDF" links on http://www.bugzilla.org/docs/ to
>   point to RTD; retain the "API" link; eliminate the "TXT" link
>
> If this sounds like a plan, I'll file some bugs.
>
> Gerv
>
>> 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
>> -
>> To view or change your list settings, click here:
>> <http://bugzilla.org/cgi-bin/mj_wwwusr?user=gerv@mozilla.org>
>>
> -
> To view or change your list settings, click here:
> <http://bugzilla.org/cgi-bin/mj_wwwusr?user=mcote@mozilla.com>