<div class="gmail_quote">On Fri, Jul 31, 2009 at 11:52 AM, Phil Christensen <span dir="ltr">&lt;<a href="mailto:phil@bubblehouse.org">phil@bubblehouse.org</a>&gt;</span> wrote:<br><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">
<br>
My only question about Sphinx, isn&#39;t it just for API docs? Also, can<br>
it interpret Zope interfaces like pydoctor can?<br>
</blockquote><div><br>Sphinx is great for writing all sorts of docs.  At its core, it&#39;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.<br>
<br>But then it&#39;s extensible...so you can write plugins for it.  One of the earliest (and included with the base package) is the &quot;autodoc&quot; 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&#39;s docstrings, though you might be able to write an extension for that.  It expects docstrings to be in RestructuredText.<br>
<br>AFAIK Sphinx does not have support for Zope interfaces, but I haven&#39;t looked in a while, and I seem to remember that someone was working on adding it...though I may be making that up.<br><br>At any rate, I think using Sphinx for Twisted&#39;s API docs (at this juncture, anyway) would be a bad idea.  But Sphinx excels at the kind of &quot;long-form, instructional&quot; docs you mention below.  I use it for all my PHP projects (which of course, the autodoc extension doesn&#39;t work on), and I&#39;m really happy with it.<br>
 </div><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;"><br>
Personally I&#39;m pretty happy with the API docs (although there&#39;s always<br>
room for improvement in the actual docstrings), I think if there&#39;s a<br>
documentation need that&#39;s more dire, it&#39;s the long-form instructional<br>
kind.<br>
</blockquote><div><br>Agreed.<br> </div><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;"><br>
I just don&#39;t want to sidetrack *that* discussion by getting into API<br>
documentation concerns.</blockquote><div><br>Double Agreed.<br> </div><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;"><br>
<font color="#888888"><br>
-phil<br>
</font><div><div></div><div class="h5"></div></div></blockquote><div><br>Kevin Horn <br></div></div><br>