I understand what you mean, but I'd rather not invest a huge amount of time into
hacking (eeeer... adjusting ;-)) Sphinx so it pulls data from MediaWiki. Do you think that
just a simple link to "Search for user documentation here <link>" would
not be sufficient?
J.
----- Original Message -----
From: "John Dulaney" <j_dulaney(a)live.com>
To: autoqa-devel(a)lists.fedorahosted.org
Sent: Wednesday, July 13, 2011 3:31:50 PM
Subject: 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.
_______________________________________________
autoqa-devel mailing list
autoqa-devel(a)lists.fedorahosted.org
https://fedorahosted.org/mailman/listinfo/autoqa-devel