[Twisted-Python] Questions about adding documentation
micahel at gmail.com
Mon Aug 3 03:59:51 EDT 2009
2009/8/3 tarjei <tarjei at nu.no>:
> A lot has been said in this discussion but I'll add one thing.
> On 07/31/2009 06: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 *replarce* 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:
> What I miss is a comment system related to the API docs so that it is
> possible for beginners and others to add small notes there without
> having to make a ticket, wait for it to be assigned etc.
I have an old, half finished idea in this area, which is that pydoctor
has a mode which runs a web server and allows you to edit the
docstrings online. It needs a bunch of work to get to useful --
probably user accounts, a way of not losing all changes when you
restart the server, a lot of polish and, indeed, maybe a comment
feature or discussion view -- but I think the idea is sound.
If you have pydoctor installed, you can try pydoctor --auto in a
directory containing some python modules.
More information about the Twisted-Python