RE: Documentation Demo with Sphinx
+1 on Kamil's thoughts.
The auto-generated documentation is great for libraries (i.e. an equivalent of pydoc),
but I would not support having "user" documentation done this way.
I believe that the first step should be 'consolidation' of all the documentation
we have, and sorting it into three categories
* code documentation
* development documentation
* user documentation
Code documentation are docstrings + possibly stuff like "ResultsDB Scheme" and
documentation tightly related to 'understanding the code'.
Development documentation would be AutoQA architecture, ResulsDB Writeup, Depcheck
descriptions...
While by user documentation, I mean stuff like "how to install autotest"
"How to update AutoQA repoinfo.conf", but also "understanding
depcheck/upgradepath errors" and other things which are not really related to the
code itself.
I don't have any problem with code and devel doc being autogenerated (and hence
tightly coupled with autoqa releases & git), but I'd like to have the users doc on
wiki.
The only thing I'd gladly got rid of is the spread of documentation between trac
& wiki. I'd keep one, and personaly prefer wiki over trac.
J.
Ok, kind of expanding on this, would it be possible to set up Sphinx so that
it does the autodoc thing with code and devel documentation, but also pull
from the Wiki for user doc? The Wiki content would still have to be human
authored, but I don't see why Sphinx can't pull from that.
Am I making sense here?
Also, +1 on keeping docs in the Wiki rather than spreading them about, no
matter whether Sphinx winds up getting used or not.
John.