[Twisted-Python] Questions about adding documentation

[Kevin Horn]

On Fri, Jul 31, 2009 at 11:52 AM, Phil Christensen <phil at bubblehouse.org>wrote:

>
> My only question about Sphinx, isn't it just for API docs? Also, can
> it interpret Zope interfaces like pydoctor can?
>

Sphinx is great for writing all sorts of docs.  At its core, it's basically
a system for gluing together a bunch of RestructiredText documents and
automatically cross-linking them, building an index, a javascript-based
search capability, handling tables of contents, and outputing the results in
various formats.

But then it's extensible...so you can write plugins for it.  One of the
earliest (and included with the base package) is the "autodoc" extension
which makes generating nice clean API docs from your docstrings.  What it
does _not_ do is process all those epydoc bits that are in Twisted's
docstrings, though you might be able to write an extension for that.  It
expects docstrings to be in RestructuredText.

AFAIK Sphinx does not have support for Zope interfaces, but I haven't looked
in a while, and I seem to remember that someone was working on adding
it...though I may be making that up.

At any rate, I think using Sphinx for Twisted's API docs (at this juncture,
anyway) would be a bad idea.  But Sphinx excels at the kind of "long-form,
instructional" docs you mention below.  I use it for all my PHP projects
(which of course, the autodoc extension doesn't work on), and I'm really
happy with it.


>
> Personally I'm pretty happy with the API docs (although there's always
> room for improvement in the actual docstrings), I think if there's a
> documentation need that's more dire, it's the long-form instructional
> kind.
>

Agreed.


>
> I just don't want to sidetrack *that* discussion by getting into API
> documentation concerns.


Double Agreed.


>
>
> -phil
>

Kevin Horn
-------------- next part --------------
An HTML attachment was scrubbed...
URL: </pipermail/twisted-python/attachments/20090731/d915c7a1/attachment.html>