[CentralOH] Sphinx

[Yung-Yu Chen]

On Wed, Nov 11, 2009 at 16:36, William McVey <wam at cisco.com> wrote:

> On Mon, 2009-11-09 at 14:24 -0500, Yung-Yu Chen wrote:
> >
> > For internal projects, I usually prefer to write API doc using epydoc
> > rather than write book-style documentation with sphinx.  Full-fledged
> > documentation is too heavy-weight to my projects, and readers are too
> > limited.  API doc is more suitable to my need.
>
> Sphinx totally allows you to build "api docs". With the
> sphinx.ext.autodoc (an extension that ships with Sphinx) extension
> enabled, it will pull documentation for your modules/class/functions
> from docstrings. If you're working with Django, there is also the
> djangodocs extension which provides easy ability to document template
> tags, filters, settings variables, and a variety of other
> django-specific project interfaces. This is for example how Django docs
> (http://docs.djangoproject.com/en/dev/) are built (which has both a
> combination of "prose style" docs as well as "api style" docs.)
>
>
It's great to know how to generate API docs with Sphinx.  I knew there's
definitely a way but couldn't find it.  Thanks a lot, William.

I think Sphinx is definitely more advanced than Epydoc.  For a project with
a potential large audience to its documentation, I guess Sphinx is a better
choice than Epydoc.  Sphinx is more versatile and more actively
developed/maintained.

However, from my experience, it took me more time in learning Sphinx than
that in learning Epydoc.  Before leaning both tools, I have been proficient
in rst/docutils for a long time but knew nothing about epytext.  Even with
the fact, Epydoc is more straight-forward to me than Sphinx.

yyc


>  -- William
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/mailman/private/centraloh/attachments/20091111/f0570069/attachment-0001.htm>