Re: Documentation Demo with Sphinx
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:
- https://github.com/tflink/autoqa-devel
* To generate the HTML docs, go to the doc/ dir and type 'make html'
Demo:
- http://tflink.fedorapeople.org/autoqa/sphinxdemo/
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.