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
I think that makes sense and shouldn't be too difficult to maintain.
// Mike