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

[Gervase Markham]

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