[CentralOH] Sphinx

Yung-Yu Chen yungyuc at gmail.com
Wed Nov 11 23:59:50 CET 2009

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

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.


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

More information about the CentralOH mailing list