I spent a little bit of time and put together a really small demo of what our documentation could look like using Sphinx (http://sphinx.pocoo.org/). I stress that this is a _demo_ and I didn't spend much time on it - the content is pretty sparse and not very good. If we're interested in looking into this more, I can spend more time on it.
For the demo, I converted the AutoQA wiki page verbatim (other than the added section for module docs) and generated doc for bodhi_utils. I listed some of what I think the advantages and disadvantages of switching to Sphinx would be.
Code:
- To generate the HTML docs, go to the doc/ dir and type 'make html'
Demo:
It really looks good. I am not sure of the immediate benefits though (when the extra work is taken into account).
* I think these auto-generated pages are good for module documentation. They really are. The question is whether we need it currently. The developers who checkout out our code will probably always look at the current doc with pydoc or some IDE or display source code. I don't see anything we currently offer to the wide public. Once we have support for user-provided tests, I agree this is a great tool to have the docs online.
* I think it's little too complicated for free-text documentation. I imagine a situation when we publish documentation like "How to write AutoQA tests" or "Depcheck help" with the new release and after a week or two we want to change something. Add more examples, fix typos, etc. Will we have to always push to git, tag it, deploy it? I don't think it worth it, at least currently. I understand it's good to have "How to write AutoQA tests" for 0.5 and for 0.6 separated and publish it only after new release. But again, I think it makes sense once we support public API for user-provided tests. Until that time it's more of a documentation for us than for anyone else.
Maybe we should separate documentation "for us, the developers" and for "the others, test writers" and then talk about them separately (location, generation, etc).
Josef has some more thoughts on this, I suppose he'll write some of them here soon.