On Sunday 04 April 2004 13:56, Chris McDonough wrote:

I'm not sure there is a rationale, other than it was composed before Interfaces existed and the "thing to do" at the time was to create docs that went into the hurt^H^H^H^Hhelp system.  I think the "real" answer would be to go and create interfaces for all API classes and turn that into an API reference (assuming people would update the interfaces when they updated the code.. but that's not a given either I guess).  I'm not sure that exposing the docstrings of the classes themselves would be much better than the current situation, but then again, I don't want to get in your way if you want to spend time on this godforsaken task.

Yeah, I guess the best way would be to do interfaces. Then you can use parts of the Zope 3 API documentation tool (actually all of the Interface and Class doc module) and generate docs. Regards, Stephan -- Stephan Richter CBU Physics & Chemistry (B.S.) / Tufts Physics (Ph.D. student) Web2k - Web Software Design, Development and Training

On Sunday 04 April 2004 15:23, Paul Winkler wrote:

...

Yeah, I guess the best way would be to do interfaces. Then you can use parts of the Zope 3 API documentation tool (actually all of the Interface and Class doc module)  and generate docs.

I note in lib/python/Interfaces/IInterface.py, there are several ways to declare interfaces currently. Is one of these preferred?

class FooBar:     implements(IFoo, IBar)

This is the only way used in Zope 3.

class FooBar:     __implements__ = (IFoo, IBar)

This is mainly for backward-compatibility, I understand. Regards, Stephan -- Stephan Richter CBU Physics & Chemistry (B.S.) / Tufts Physics (Ph.D. student) Web2k - Web Software Design, Development and Training

On Sun, Apr 04, 2004 at 01:56:21PM -0400, Chris McDonough wrote:

I'm not sure there is a rationale, other than it was composed before Interfaces existed and the "thing to do" at the time was to create docs that went into the hurt^H^H^H^Hhelp system. I think the "real" answer would be to go and create interfaces for all API classes and turn that into an API reference (assuming people would update the interfaces when they updated the code.. but that's not a given either I guess).

yes, that is a risk. OTOH that's true of the current situation anyway.

I'm not sure that exposing the docstrings of the classes themselves would be much better than the current situation,

well, it would arguably make it marginally more likely that the api reference is updated when the code is updated. and maybe make it a bit easier for zope newbies to explore the codebase. "I grepped for ObjectManagerItem but it doesn't seem to exist" :-( But I tend to agree that Interfaces are the Right Thing here and would make it easier to extract docs.

but then again, I don't want to get in your way if you want to spend time on this godforsaken task.

:-) if we can safely assume that zope 2 is going to have a useful life measured in years from today, I think the task is worthwhile. I've seen a few of these "hurt^H^H^H^Hhelp" jokes lately, and the user comments on the online API reference are rather grim.

Adding insult to injury, I can't seem to get to zope.org... at least each request takes more than an embarrassing 10 seconds, and I'm way too impatient to wait for it, so I can't verify that the real"API reference" doesn't span more than the OFS help system docs. I think it may... IIRC DateTime, ZCatalog, and others are a part of the API reference.

Yes, those are in there along with many other standard Products. The current set of modules listed in the API reference are: AccessControl AuthenticatedUser DTMLDocument DTMLMethod DateTime ExternalMethod File Folder Image MailHost ObjectManager ObjectManagerItem PropertyManager PropertySheet PropertySheets PythonScript Request Response SessionInterfaces TransienceInterfaces UserFolder Vocabulary ZCatalog ZSQLMethod ZTUtils math random sequence standard string This is somewhat misleading as File is not a module and ObjectManagerItem is completely fictitious. There may be other such "helpful" inaccuracies. There are probably a bunch of things missing from that list too. E.g. OFS.Cache.* comes to mind. -- Paul Winkler http://www.slinkp.com Look! Up in the sky! It's ULTRA SINGLE MOTHER SPOOK! (random hero from isometric.spaceninja.com)

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)

I've posted my proposal: http://dev.zope.org/Wikis/DevSite/Proposals/SanitizeHelpSysAndAPIReference """ Motivation The current Help system in Zope 2 is sometimes jokingly referred to as the "hurt^H^H^H^Hhelp" system. The online API reference in the Zope Book, which AFAICT is extracted from the help system, contains a number of disparaging and disappointed comments from users. Problems include: * incomplete (methods and entire classes are missing) * lack of useful examples * doesn't always match the source code (e.g. ObjectManagerItem does not really exist) * online version is hard to navigate * synchronizing the online BackTalk version with the help system is a laborious manual process """ -- Paul Winkler http://www.slinkp.com Look! Up in the sky! It's FJUKY DANCER ECCENTRIC! (random hero from isometric.spaceninja.com)

On Sun, Apr 04, 2004 at 05:02:39PM -0400, Chris McDonough wrote:

FWIW, the old Zope Book sourceforge project (where?) had some code to generate the API reference chapter from the helpsys. I didn't use it because the API reference was "stepchilded" during the Zope Book rewrite, but it could be useful somehow.

found it, thanks! http://cvs.sourceforge.net/viewcvs.py/zope-book/Book/appendix_b.py -- Paul Winkler http://www.slinkp.com Look! Up in the sky! It's UNDERWEAR INSPECTOR-CHUCKER! (random hero from isometric.spaceninja.com)

On Sun, 4 Apr 2004 17:50:13 -0400 Paul Winkler <pw_lists@slinkp.com> wrote:

I've posted my proposal: http://dev.zope.org/Wikis/DevSite/Proposals/SanitizeHelpSysAndAPIReference

I am 100% for this proposal and I have been thinking on and off about the same thing for years. I agree that we need to create interfaces everywhere. With that I propose the following to prevent future help skew: - That all interfaces in the system be verified in unittests. - We eliminate the duplicate interfaces currently used by the help system (Some of these are actually fairly up-to-date, so we should look at them first). - If we create examples that they be runnable doctests, which are executed by test.py The latter may mean we need a better integration test framework, I don't know. I think we'd need to try out a few and see. I can certainly help here. IMO this is a task ripe for a "divide and conquer" strategy. Maybe we should have a "Help Day" to kick this off? -Casey

On Mon, 5 Apr 2004 11:00:59 -0400 Paul Winkler <pw_lists@slinkp.com> wrote:

On Mon, Apr 05, 2004 at 09:44:30AM -0400, Casey Duncan wrote:

...

On Sun, 4 Apr 2004 17:50:13 -0400 Paul Winkler <pw_lists@slinkp.com> wrote:

...

I've posted my proposal: http://dev.zope.org/Wikis/DevSite/Proposals/SanitizeHelpSysAndAPIReference

I am 100% for this proposal and I have been thinking on and off about the same thing for years. I agree that we need to create interfaces everywhere. With that I propose the following to prevent future help skew:

- That all interfaces in the system be verified in unittests.

Pardon my ignorance, but what tests can you write for an interface?

You can verify that a class or object implements an interface using the Verify module of the Interface package. It give you at least some protection against interface changes. It doesn't protect against all skew (the object can implement a superset of the interface and still verify), but it at least performs a sanity check. Whenever I write tests, the first one is generally an interface check. It might be nice to think about ways to make this check more rigorous. For example, methods protected by permissions or marked public should *always* be part of an interface. We could write a check to make sure that the interfaces implemented by an object cover all of the published API of that object. The deep inheritance in Zope2 might make that tricky, but it's food for thought. A *very nice* side-affect of all this will be that we will have interface coverage throughout Zope2 (and at least minimal test coverage to check the interface). This will obviously help integrating with Zope3 down the line. -Casey

Paul Winkler wrote:

...

I'm not sure that exposing the docstrings of the classes themselves would be much better than the current situation,

well, it would arguably make it marginally more likely that the api reference is updated when the code is updated.

Indeed. I think using interfaces and docstrings would be good, as twisted does: http://www.twistedmatrix.com/documents/current/api/index.html http://www.twistedmatrix.com/documents/current/api/twisted.application.servi... Who knows, it might even result in some docstrings getting updated :-) At worst, it'll mean that people don't have to update 3 sets of (what should be) identical documentation, as is currently the case... cheers, Chris -- Simplistix - Content Management, Zope & Python Consulting - http://www.simplistix.co.uk

On Mon, Apr 05, 2004 at 06:56:40AM -0400, Stephan Richter wrote:

I think the Zope 3 API docs are much nicer than the Twisted ones above. I have put a lot of time into Zope 3's version, so that it is as usable as possible. You should check it out. Start Zope 3 and go to:

http://localhost:8080/++apidoc++

It does look pretty nice!

As said before, I am fairly convinced that most of the code could be reused for the Zope 2 version. This will be especially interesting when Zope 3 will be available in Zope 2.8 or 2.9.

I'm into it. But I don't think we should hold up zope 2.8 waiting for all docs to be moved into interfaces. Can we put this on the release plan for 2.9? -- Paul Winkler http://www.slinkp.com Look! Up in the sky! It's ENGINEER KO! (random hero from isometric.spaceninja.com)

On Monday 05 April 2004 03:49, Dieter Maurer wrote:

Chris McDonough wrote at 2004-4-4 13:56 -0400:

...

... I think the "real" answer would be to go and create interfaces for all API classes and turn that into an API reference

*BEWARE* however, that interfaces lack information *VITAL* for an API reference: the constructor description!

It is totally legal to add the constructor to the interface. We do this in Zope 3 at some places too, like for adapters and views. Regards, Stephan -- Stephan Richter CBU Physics & Chemistry (B.S.) / Tufts Physics (Ph.D. student) Web2k - Web Software Design, Development and Training

On Monday 05 April 2004 11:38, Paul Winkler wrote:

I'm not sure if that's what Dieter meant, but in any case, there is another thing we need documented for zope 2: product constructors. These are factory functions, e.g.:

def manage_addPythonScript(self, id, REQUEST=None, submit=None):     """Add a Python script to a folder.     """     ...

Do the zope 3 doc tools provide support for such functions? I didn't spot any in a quick bit of browsing, but I certainly didn't read the whole reference.

Actually it does document functions, as they are valid components. However, they are not listed in any registry at the moment, so that you can get to their documentation only by browsing the "Classes" doc module. Regards, Stephan -- Stephan Richter CBU Physics & Chemistry (B.S.) / Tufts Physics (Ph.D. student) Web2k - Web Software Design, Development and Training