[Zope-dev] Reasons for the current API reference docs implementation?
Howdy, I was thinking of writing a proposal for killing the current API reference (in lib/python/Products/OFSP/help) and replacing it with the actual docstrings of the actual classes. But before I write the proposal ... can somebody tell me what was the rationale for the way it is? -- Paul Winkler http://www.slinkp.com Look! Up in the sky! It's RASTA BAT KAZUE! (random hero from isometric.spaceninja.com) ___ Zope-Dev maillist - [EMAIL PROTECTED] http://mail.zope.org/mailman/listinfo/zope-dev ** No cross posts or HTML encoding! ** (Related lists - http://mail.zope.org/mailman/listinfo/zope-announce http://mail.zope.org/mailman/listinfo/zope )
Re: [Zope-dev] Reasons for the current API reference docs implementation?
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. 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 realAPI 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. - C On Fri, 2004-04-02 at 12:46, Paul Winkler wrote: Howdy, I was thinking of writing a proposal for killing the current API reference (in lib/python/Products/OFSP/help) and replacing it with the actual docstrings of the actual classes. But before I write the proposal ... can somebody tell me what was the rationale for the way it is? ___ Zope-Dev maillist - [EMAIL PROTECTED] http://mail.zope.org/mailman/listinfo/zope-dev ** No cross posts or HTML encoding! ** (Related lists - http://mail.zope.org/mailman/listinfo/zope-announce http://mail.zope.org/mailman/listinfo/zope )
Re: [Zope-dev] Reasons for the current API reference docs implementation?
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 ___ Zope-Dev maillist - [EMAIL PROTECTED] http://mail.zope.org/mailman/listinfo/zope-dev ** No cross posts or HTML encoding! ** (Related lists - http://mail.zope.org/mailman/listinfo/zope-announce http://mail.zope.org/mailman/listinfo/zope )
Re: [Zope-dev] Reasons for the current API reference docs implementation?
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 realAPI 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) ___ Zope-Dev maillist - [EMAIL PROTECTED] http://mail.zope.org/mailman/listinfo/zope-dev ** No cross posts or HTML encoding! ** (Related lists - http://mail.zope.org/mailman/listinfo/zope-announce http://mail.zope.org/mailman/listinfo/zope )
Re: [Zope-dev] Reasons for the current API reference docs implementation?
On Sun, Apr 04, 2004 at 02:24:55PM -0400, Stephan Richter wrote: 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. 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) class FooBar: __implements__ = (IFoo, IBar) -- Paul Winkler http://www.slinkp.com Look! Up in the sky! It's TITANIUM FUNCTIONARY SONGSTRESS! (random hero from isometric.spaceninja.com) ___ Zope-Dev maillist - [EMAIL PROTECTED] http://mail.zope.org/mailman/listinfo/zope-dev ** No cross posts or HTML encoding! ** (Related lists - http://mail.zope.org/mailman/listinfo/zope-announce http://mail.zope.org/mailman/listinfo/zope )
Re: [Zope-dev] Reasons for the current API reference docs implementation?
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 ___ Zope-Dev maillist - [EMAIL PROTECTED] http://mail.zope.org/mailman/listinfo/zope-dev ** No cross posts or HTML encoding! ** (Related lists - http://mail.zope.org/mailman/listinfo/zope-announce http://mail.zope.org/mailman/listinfo/zope )
Proposal: Sanitize HelpSys API Reference, was Re: [Zope-dev] Reasons for the current API reference docs implementation?
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) ___ Zope-Dev maillist - [EMAIL PROTECTED] http://mail.zope.org/mailman/listinfo/zope-dev ** No cross posts or HTML encoding! ** (Related lists - http://mail.zope.org/mailman/listinfo/zope-announce http://mail.zope.org/mailman/listinfo/zope )
Re: [Zope-dev] Reasons for the current API reference docs implementation?
On Sun, Apr 04, 2004 at 04:21:16PM -0400, Stephan Richter wrote: 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. got it, thanks. -- Paul Winkler http://www.slinkp.com Look! Up in the sky! It's THE GARAGE! (random hero from isometric.spaceninja.com) ___ Zope-Dev maillist - [EMAIL PROTECTED] http://mail.zope.org/mailman/listinfo/zope-dev ** No cross posts or HTML encoding! ** (Related lists - http://mail.zope.org/mailman/listinfo/zope-announce http://mail.zope.org/mailman/listinfo/zope )
Re: Proposal: Sanitize HelpSys API Reference, was Re: [Zope-dev] Reasons for the current API reference docs implementation?
On Sun, 2004-04-04 at 17:50, Paul Winkler wrote: 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 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. - C ___ Zope-Dev maillist - [EMAIL PROTECTED] http://mail.zope.org/mailman/listinfo/zope-dev ** No cross posts or HTML encoding! ** (Related lists - http://mail.zope.org/mailman/listinfo/zope-announce http://mail.zope.org/mailman/listinfo/zope )
Re: [Zope-dev] Reasons for the current API reference docs implementation?
On Sun, 2004-04-04 at 15:20, 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. 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. The objects must have a docstring to be publishable misfeature works against us here too if you want to get docs from code. There are many things that are not web-callable that are part of the API. 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. 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. 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) could be dealt with when the interfaces are complete (which may be never, but that's really ok). :-) 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. Yes, it's definitely a weak spot. 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. Yeah. The list has grown, but the docs haven't kept up. - C ___ Zope-Dev maillist - [EMAIL PROTECTED] http://mail.zope.org/mailman/listinfo/zope-dev ** No cross posts or HTML encoding! ** (Related lists - http://mail.zope.org/mailman/listinfo/zope-announce http://mail.zope.org/mailman/listinfo/zope )
Re: Proposal: Sanitize HelpSys API Reference, was Re: [Zope-dev] Reasons for the current API reference docs implementation?
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) ___ Zope-Dev maillist - [EMAIL PROTECTED] http://mail.zope.org/mailman/listinfo/zope-dev ** No cross posts or HTML encoding! ** (Related lists - http://mail.zope.org/mailman/listinfo/zope-announce http://mail.zope.org/mailman/listinfo/zope )
Re: [Zope-dev] Reasons for the current API reference docs implementation?
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) ___ Zope-Dev maillist - [EMAIL PROTECTED] http://mail.zope.org/mailman/listinfo/zope-dev ** No cross posts or HTML encoding! ** (Related lists - http://mail.zope.org/mailman/listinfo/zope-announce http://mail.zope.org/mailman/listinfo/zope )
Re: [Zope-dev] Reasons for the current API reference docs implementation?
On Sun, 2004-04-04 at 18:15, Paul Winkler wrote: 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? Yup... 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. It isn't, I just hate it. ;-) - C ___ Zope-Dev maillist - [EMAIL PROTECTED] http://mail.zope.org/mailman/listinfo/zope-dev ** No cross posts or HTML encoding! ** (Related lists - http://mail.zope.org/mailman/listinfo/zope-announce http://mail.zope.org/mailman/listinfo/zope )
Re: [Zope-dev] ZODB with twisted web.
On Fri, 2004-04-02 at 17:37, Dieter Maurer wrote: Syver Enstad wrote at 2004-4-2 11:38 +0200: I am checking out how to use ZODB with twisted web. I thought that I would have the DB instance globally accesible and call the open method to get a connection on each request. I thought that if I use connection.getTransaction().commit() before sending the response I will commit on the connection for that request. Is this necesarily true when using twisted web because it is single threaded and it seems that ZODB finds the correct transaction by checking the thread. This is true only, when you are working with local transaction mode (i.e. you are calling connection.setLocalTransaction()). Currently, this mode restricts you to a single transaction client. Neither relational databases nor other transactional clients understand this mode. Moreover, you cannot use DBTab to mount several ZODB storages. i wouldnt say it restricts you to a single txn client, local transaction mode with twisted allows for the primary goal of using single threaded twisted with zodb txn semantics bound to protocol instances/clients, and the txn framework is still perfectly capable, just that the resource integration of other txn aware resources needs to play well with zodb conn based txns, which basically rules out most of the existing zope products as they use a global accessor to the transaction as opposed to call getTransaction on a conn which would still allow zodb to play a txn authority/manager role. but at the level of using twisted and zodb directly those products wouldn't likely be all that useful. -cheers, -kapil ___ Zope-Dev maillist - [EMAIL PROTECTED] http://mail.zope.org/mailman/listinfo/zope-dev ** No cross posts or HTML encoding! ** (Related lists - http://mail.zope.org/mailman/listinfo/zope-announce http://mail.zope.org/mailman/listinfo/zope )
