On Fri, 17 Jun 2011 01:39:22 -0400 (EDT)
Hongqing Yang <hoyang(a)redhat.com> wrote:
----- Original Message -----
> From: "Tim Flink" <tflink(a)redhat.com>
> To: autoqa-devel(a)lists.fedorahosted.org
> Sent: Friday, June 17, 2011 1:27:09 PM
> Subject: Re: AutoQA Documentation
> On Thu, 16 Jun 2011 22:37:57 -0400 (EDT)
> Hongqing Yang <hoyang(a)redhat.com> wrote:
> > Hi, All
> >
> > For our AutoQA code released, I prefer to use EpyDoc
> >
http://epydoc.sourceforge.net/ to document them, It will help
> > others to understand. For other documents I think It is better to
> > create a portal in the wiki, or it is really not easy to find the
> > document when you do not know it.
>
> Out of curiosity, why epydoc over sphynx with autodoc [1] and/or
> autosummary [2]?
>
> My concern about epydoc is that it doesn't seem to be changing much
> anymore. According to sourceforge, there haven't been any commits in
> the last year and no releases since January, 2008.
>
> From what I understand Sphinx wouldn't be quite as automatic as
> epydoc but it is a lot more flexible since it doesn't enforce the
> javadoc like
> tree structure of the docs.
>
> Do you think that splitting up API documentation from the other docs
> is
> better than keeping them together, and having a main page or am I
> misunderstanding what you mean by a portal?
>
> Tim
>
> [1]
http://sphinx.pocoo.org/ext/autodoc.html
> [2]
http://sphinx.pocoo.org/ext/autosummary.html
>
Hi Tim,
I have not explored the sphynx, we can compare these.
The portal here is the same meaning with main page, the purpose is
that the users can follow links to the contents like Content
Management System.
Would the front pages of the online python docs [1] or py.test [2] fit
with what you were thinking of?
I think that you're probably right, a comparison would be useful. I
don't have a whole lot of experience with either tool - I've worked
more with doxygen and javadoc.
Tim
[1]