Re: Documentation Demo with Sphinx

[Josef Skladanka]

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" 
> To: [e-mail]
> 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
> [e-mail]
> https://fedorahosted.org/mailman/listinfo/autoqa-devel