On Fri, Jul 31, 2009 at 11:52 AM, Phil Christensen <phil@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