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
signature.asc
Description: PGP signature
_______________________________________________ qa-devel mailing list qa-devel@lists.fedoraproject.org https://admin.fedoraproject.org/mailman/listinfo/qa-devel
