This ticket is a duplicate of https://pagure.io/taskotron/libtaskotron/issue/11

As per the qa devel meeting [1], I'll initially be doing a comparison between Sphinx [2] and Dexy [3] - with examples for both.

[1] http://meetbot.fedoraproject.org/fedora-blocker-review/2014-01-13/fedoraqa-devel.2014-01-13-17.12.html
[2] http://sphinx-doc.org/
[3] http://dexy.it/

The tutorial for this is finished - so people can start installing their own instances of Taskotron.

Currently there is a dexy generated tutorial [1] and a sphinx generated one [2]. Working on a comparison of the tools right now - so far I prefer dexy, even if the docs are a bit disjointed (IMO).

// Roshi

[1] http://roshi.fedorapeople.org/dexy-themed
[2] http://roshi.fedorapeople.org/sphinx

In Dexy version I'm really missing the option to see anchors of section headers (either using TOC or the nifty pop-up icons as in Sphinx). Can that be added?

That can be added. That template is the all of one line added to the baseweb temaplate - """ {{ content }} """ It does provide access for those kinds of navigation. You can do anything jinja can do.

I've written a blog post about sphinx/dexy [1]. At the end of the day, both tools do the same thing. There isn't a gigantic difference between the two. For our purposes, I lean towards Dexy. It easily incorporates all sorts of inputs as well as languages - though sphinx can as well. I really wish I had found some 'killer' feature that made the decision easy, but both tools do what we need - it comes down to what we prefer. Any thoughts?

// Roshi

[1] http://roshi.fedorapeople.org/comparing-dexy-and-sphinx.html

Source for the tutorials is located here: https://bitbucket.org/Rorosha/doc-tools

After some discussion on qadevel@, I proposed that we use sphinx for code docs and dexy for things which aren't really development related.

https://lists.fedoraproject.org/pipermail/qa-devel/2014-January/000768.html

All responses to that proposal were positive, so I consider this issue closed.