On Thu, 30 Jan 2014 16:55:49 -0700 Tim Flink <tfl...@redhat.com> wrote:
> On Tue, 28 Jan 2014 09:09:56 -0700 > Mike Ruckman <ro...@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
signature.asc
Description: PGP signature
_______________________________________________ qa-devel mailing list qa-devel@lists.fedoraproject.org https://admin.fedoraproject.org/mailman/listinfo/qa-devel