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

classic Classic list List threaded Threaded
7 messages Options
Reply | Threaded
Open this post in threaded view
|

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

Gervase Markham
Hi everyone,

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.

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
[hidden email]
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=lists+s6506n84121h51@...>
Reply | Threaded
Open this post in threaded view
|

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

Colin Ogilvie
On 31 August 2013 14:35, Gervase Markham <[hidden email]> wrote:
Hi everyone,

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.

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?

I think this seems like quite a good idea, to be honest...

I did find a more up-to-date db2rst script at https://github.com/kurtmckee/db2rst which might help? I've not tried it as I'm not sure what changes you'd made in the first place.

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

Colin 
Reply | Threaded
Open this post in threaded view
|

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

Gervase Markham
On 31/08/13 20:51, Colin Ogilvie wrote:
> I did find a more up-to-date db2rst script
> at https://github.com/kurtmckee/db2rst which might help? I've not tried
> it as I'm not sure what changes you'd made in the first place.

Thanks for the tip - although the amount of data is small enough and the
current script is good enough that I think that, if we decide to switch,
we should just run the current script and then fix up the result by hand
and never use it again...

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

I think Sphinx has contents auto-generation that we could use if we hook
it all up properly.

Gerv
-
To view or change your list settings, click here:
<http://bugzilla.org/cgi-bin/mj_wwwusr?user=lists+s6506n84121h51@...>
Reply | Threaded
Open this post in threaded view
|

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

Gervase Markham
In reply to this post by 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
> [hidden email]
> 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@...>
>
-
To view or change your list settings, click here:
<http://bugzilla.org/cgi-bin/mj_wwwusr?user=lists+s6506n84121h51@...>
Reply | Threaded
Open this post in threaded view
|

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

Dave Miller
Sounds like a plan. I like it.

Gervase Markham <[hidden email]> 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 th at 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
[hidden email]
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@...>

-
To view or change your list settings, click here:
<http://bugzilla.org/cgi-bin/mj_wwwusr?user=justdave@...>

--
Sent from my Android phone with K-9 Mail. Please excuse my brevity.
Reply | Threaded
Open this post in threaded view
|

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

Gervase Markham
On 03/09/13 12:01, Dave Miller wrote:
> Sounds like a plan. I like it.

https://bugzilla.mozilla.org/show_bug.cgi?id=912064 .

Gerv
-
To view or change your list settings, click here:
<http://bugzilla.org/cgi-bin/mj_wwwusr?user=lists+s6506n84121h51@...>
Reply | Threaded
Open this post in threaded view
|

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

Mark Côté
In reply to this post by Gervase Markham
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
>> [hidden email]
>> 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@...>
>>
> -
> To view or change your list settings, click here:
> <http://bugzilla.org/cgi-bin/mj_wwwusr?user=mcote@...>

-
To view or change your list settings, click here:
<http://bugzilla.org/cgi-bin/mj_wwwusr?user=lists+s6506n84121h51@...>