[utah-devel] Sphinx documentation

[Javier Collado]

Hello all,

I've pushed a branch with an example of the documentation from the wiki 
using rst with sphinx (still incomplete since it's just an experiment). 
The branch url, in case you want to take a look at it, is:
lp:~javier.collado/utah/sphinx-docs

I've also created a project in readthedocs.org to make the documentation 
from the branch available here:
http://utah.readthedocs.org/en/latest/

The aim of having all this is twofold:
- Having the documentation in the same location as the code (and 
discourage merge proposals that don't include documentation changes).
- Have always an up-to-date version of the documentation available

Regarding the second bullet above, the idea is that readthedocs.org 
takes care of building the documentation for you every 24 hours (I 
believe) or, if you need more, using a URL as a signal that a new build 
is needed. To use the URL we just need to use a bazaar hook, so that 
when a branch (it should work for both trunk and dev) is pushed an HTTP 
GET request is sent. I already used it for testmanager and worked fine.

The drawback, is that there's no integration with wiki.ubuntu.com (even 
the markup is different), so that's why I'm sending this e-mail. In my 
opinion the advantages are worth the change (we can always add a link in 
the wiki to readthedocs.org), but I'd like to know if you have any 
comments/concern about this. Thanks.

Best regards,
     Javier