[Zope-dev] Reasons for the current API reference docs implementation?

[Paul Winkler]

On Sun, Apr 04, 2004 at 05:06:52PM -0400, Chris McDonough wrote:
> The "objects must have a docstring to be publishable" misfeature works
> against us here too if you want to get docs from code.

But that would be a non-issue if I create interfaces, right?

> ... Making
> interfaces does seem like the "right thing".   It also implies that
> whoever does it knows what the interfaces *are*, which is a subjective
> issue itself.

granted.

> Right now, the help system "interfaces" are completely
> ignored (by everyone except those who need it most: people who first
> come to Zope).  Marking up Zope classes with interfaces is a really huge
> task because it will lead to many dark alleyways of Zope history and
> will undoubtedly lead to siutations of "I wanna change this because it's
> too embarrassing/complex to document".
> 
> That said, if it could be done maybe one module at a time, it's a doable
> task I think.  Maybe use short-lived "interface-markup" branches for
> each Zope module.

mm, you might have a point there. I'll change the proposal accordingly.

> Just pick a module to mark up with interfaces, make
> the branch, do the interfaces, ask for comments on maillists, and
> merge.  Wash, rinse, repeat for each module.  It will take a long time,
> but at least it would be in-progress.  Dealing with the presentation
> aspect (which IMHO involves killing the help system and replacing it
> with simple files on a filesystem or chapters in an online book)

why is killing the current help system necessary? I was thinking of 
keeping it but having it use docs from these proposed interfaces.

-- 

Paul Winkler
http://www.slinkp.com
Look! Up in the sky! It's POTATO-FRY COOK!
(random hero from isometric.spaceninja.com)