On Tue, 28 Jan 2014 09:09:56 -0700
Mike Ruckman <roshi(a)fedoraproject.org> wrote:
I've posted a comparison between Sphinx and Dexy [1] - as well
as
updated the phabricator ticket [2]. The tools are pretty similar in
what they can produce, so it really comes down to what people are
comfortable with. The learning curve for Dexy isn't steep, and I think
it's just enough easier to use compared to Sphinx for our purposes.
I wasn't able to find air-tight reasoning for one over the other for
qa-devel work - but found dexy a bit easier to use and template.
Source for both tutorials can be found on my bitbucket profile [3].
As mike started the evaluation, the goal was to see which of the two
tools would be better for qa-devel (and possibly qa) as a whole and end
up with one documentation tool.
As I'm looking through the demo that he came up, adding in my own
experience and what nick said about
rtd.org, I'm wondering if we really
need or want to have a single tool.
As I see it, both sphinx and dexy have their advantages and
disadvantages. Sphinx is probably better for documenting a software
project and dexy is probably better for more general documentation.
The main general advantage I see to dexy is that it makes theming and
customization of output much less painful when we want to make stuff
look more fedora-y. However, one of my goals for taskotron is not to
restrict it to Fedora and thus, fedora branding for taskotron-specific
docs is a bit of an anti-goal.
I have two reasons for wanting to keep taskotron as distro-neutral as
reasonably possible:
1. One thing that Kamil said about a year ago now is that there are
several interesting automation platforms out there but it's a shame
that they're all really purpose-specific. I agree and see no reason
to limit taskotron to Fedora from the start - if we can sanely make
at least the core bits generic, that'll only increase the possible
user/contributor base going forward.
2. For me, one of the overarching lessons from autoqa is that tight
coupling leads to pain, lots of pain. AutoQA doesn't really work
well for anything but Fedora or outside the production
infrastructure. While not directly related, I do see a correlation
between keeping the core bits distro agnostic and not repeating some
of the problematic parts of autoqa - it forces us to decouple some
things and isolate the Fedora specific bits.
With this in mind, I propose that we use sphinx and
rtd.org for
taskotron and self-hosted dexy for the less structured qadevel landing
page which points to various docs and resources.
Thoughts?
Tim