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

[Dave Miller]

Sounds like a plan. I like it.

Gervase Markham <gerv at mozilla.org> 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=justdave@bugzilla.org>

-- 
Sent from my Android phone with K-9 Mail. Please excuse my brevity.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.bugzilla.org/pipermail/developers/attachments/20130903/63b3863b/attachment.html>