[Twisted-Python] Questions about adding documentation

[Phil Christensen]

On Jul 31, 2009, at 12:32 PM, Reza Lotun wrote:
>> Even if I re-suggested the wiki based documentation, I think it's
>> important to be extra careful on how it's used. One thing I  
>> personally
>> hate is projects whose documentation is basically wiki-based, and  
>> what
>> you end having is a disconnected set of tips, many out of date, of  
>> how
>> to do this and that. It could be OK it it's labeled 'Tipi-wiki' but  
>> not
>> 'Documentation' :).
>
> I agree - the wiki shouldn't *replace* the documentation, but the
> reality is I have loads of bookmarks of blog posts and discussions on
> the mailing list, and it'd be nice if I could to go one place to find
> all that type of info. A "recipe" or "cookbook" wiki might be all we
> need, with the ability to comment on each. The Activestate Python
> Cookbook is kinda what I'm thinking about:
> http://code.activestate.com/recipes/langs/python/

I agree with all of the above. A wiki is nice when there is no  
suitable formal documentation available for a topic. I think I may  
have used the aphorism once before, "documentation is like sex, when  
it's good, it's great, when it's bad it's still better than  
nothing." (no offense intended to any with delicate sensibilities,  
btw ;-)

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

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.

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

-phil