Hello all, I've just started working on zope, coming from java servlet land. so far i'm very happy with my ability to get up and running quickly, its seems to be a great framework that allows very fast development. i am having trouble with the API documentation. i was looking for the full documentation of the request class API, and found this: http://www.zope.org/Documentation/Books/ZopeBook/2_6Edition/AppendixB.stx#2-... but this seems to be more an overview than a formal API document. for instance one of the user comments mentions the existance of an attribute called "form" that is a dictionary, and i used it in a script and it worked. but nowhere in the request class documentation does it mention that attribute. i took a guess that if "form" was an attribute, so was "cookies" and sure enough, there it was. is there a more complete API reference available, and if not how can i contribute to the update of the curent API to a more complete status? thanks, dave
David Evans wrote at 2004-9-26 15:57 -0400:
... is there a more complete API reference available, and if not how can i contribute to the update of the curent API to a more complete status?
You can ask Zope to show you (most of) the request attributes. In "ZPT" it looks like: <div tal:content="structure request" /> in DTML is it: <dtml-var REQUEST> -- Dieter
On Mon, 2004-09-27 at 13:24, Dieter Maurer wrote:
David Evans wrote at 2004-9-26 15:57 -0400:
... is there a more complete API reference available, and if not how can i contribute to the update of the curent API to a more complete status?
You can ask Zope to show you (most of) the request attributes.
In "ZPT" it looks like:
<div tal:content="structure request" />
in DTML is it:
<dtml-var REQUEST>
Thanks, thats definately helpful. However, i was really looking for something more formal. A listing of all methods and attributes of the class and the parameters and return types of the methods. I found something close at: http://ingo.fargonauten.de/epydoc/ but the ZPublisherHTTPRequest class listed does not list the "form", "cookies" or "other" attribute. I looked in the zope directory on my server and found: lib/python/ZPublisher/HTTPRequest.py this seems to be the class printed by: <div tal:content="structure request" /> so maybe the answer to my question is "read the f-in source code" :) dave
From: "David Evans" <dsevans@berndtgroup.net>
On Mon, 2004-09-27 at 13:24, Dieter Maurer wrote:
David Evans wrote at 2004-9-26 15:57 -0400:
... is there a more complete API reference available, and if not how can i contribute to the update of the curent API to a more complete status?
You can ask Zope to show you (most of) the request attributes.
In "ZPT" it looks like:
<div tal:content="structure request" />
in DTML is it:
<dtml-var REQUEST>
Thanks, thats definately helpful. However, i was really looking for something more formal. A listing of all methods and attributes of the class and the parameters and return types of the methods. I found something close at: http://ingo.fargonauten.de/epydoc/
but the ZPublisherHTTPRequest class listed does not list the "form", "cookies" or "other" attribute. I looked in the zope directory on my server and found: lib/python/ZPublisher/HTTPRequest.py
this seems to be the class printed by: <div tal:content="structure request" />
so maybe the answer to my question is "read the f-in source code" :)
To get info on a specific Product/Module (for which no documentation is readily at hand) you can create a 'quick and dirty' external method which contains: from Productxxx import Moduleyyy def getInfo(self): return str(dir(Moduleyyy)) This would return a list of the attributes of Moduleyyy. You can then append the attribute name to the Module name to drill down, eg. return str(dir(Moduleyyy.attrA) You can use the 'Test' tab on the external method object page in the ZMI to quickly run the external method. HTH Jonathan
On Sun, Sep 26, 2004 at 03:57:49PM -0400, David Evans wrote:
is there a more complete API reference available, and if not how can i contribute to the update of the curent API to a more complete status?
I've volunteered as editor of the API reference for the next (2.7) edition of the Zope Book. Help would be greatly appreciated. The version I'm working on is here: http://www.plope.com/Books/2_7Edition/AppendixB.stx Note the current TODO list here: http://www.plope.com/Books/2_7Edition/AppendixB.stx#1-2 Currently what I'm doing is the first item on that list. A BIG help would be to take responsibility for one or more remaining modules on the list below. * For all modules, classes, methods, and functions in the reference: * verify that all names are correct * see if any non-private methods are missing, and add them * compare API reference to source docstrings and to the HelpSys .stx files, combine and edit all for completeness and clarity. * check base classes for things that need documenting - either add the base class to this API ref, or document any non-overridden methods as part of the derived class docs - not sure how best to do this so i'm handling it on a case-by-case basis. It's a big job, best done one module at a time. So far it takes me about an hour to do one module properly :-( Some modules are done, see DONE below. The below modules are still to do:: PropertySheet PropertySheets PythonScripts Script SessionInterfaces TransienceInterfaces UserFolder Vocabulary ZCatalog ZSQLMethod ZTUtils math random sequence standard string -- Paul Winkler http://www.slinkp.com
Paul, First, thank you for taking on a big responsibility. That is my personal thanks, but I think the entire Zope community owes you a thanks. As a bare minimum, I would like to volunteer for one module. Hopefully more, but let's see how it goes. I have considerable experience as a programmer in C, and some in C++ and Python. I have also done my share of documentation in my time and I can write OK, but tend to be boring in my writing (typical engineer). I do have a number of comments/questions about Zope documentation in general: - As a user, I find the documentation quite useful, but not well structured compared to other documentation projects that I have seen. It leads me to wonder if any one group of people are responsible for planning the overall documentation, or did it just evolve? - What comes to mind about the API documentation is my surprise that it is included in the Zope Book in the first place. As a user, I'm much happier using a UNIX manual page or the python html reference information. Has any thought been given to taking the API out of the Zope book and making a stand alone version in XML. Ideally, this API should be available online, but also easily printable so I can put a ZOPE API reference on my book shelf. My experience is that I use online documentation much more, and more efficiently, but sometimes it is tough to beat thumbing through a hard copy. To be honest, I have not used the HelpSys in Zope and maybe this is what I'm looking for with respect to online help. - My opinion is that if reference material is more modular, then the documentation will never be up to date - but, it will evolve more quickly, especially since developers can then update documentations in small increments. - I'm not too experienced in Zope and I'm afraid I will need support in my effort to provide documentation. I think the need for support will diminish as I come up to speed. I wonder how many others out there think of volunteering, but don't because they don't feel they can contribute? It would be interesting to see the existing Zope community be more 'newbie friendly' and to let the newbies know that they are welcome and will be supported as they make their contributions. Personally, I have gotten so much out of Zope already, that I feel obligated to put something back in to it. - I assume there is a group of people to help with the documentation? How big is the group? How is it structured? Is there a group that works on the Zope Book and another that works on the Developers Guide, which I believe needs updating even more than the Zope Book. - Is the documentation kept in CVS or some other repository? - What is the time frame for reviewing a module? I know you said it takes you an hour to do a good job on a module. I suspect it will take me 10 times that on my first module because I'll have questions about it. If I commit to have it done in 10 calendar days, is that all right? - The base class documentation needs to be consistent. In my opinion, all (public) base classes need to be documented individual in the API and reference in derived classes. The last thing you want to do is document base class methods in each derived class (what a mess that would be.) - Speaking of classes, I would really like to see some kind of URL document for Zope included in the developers guide (different topic I guess - sorry) - Do I use Zope 2.7.3 source code for the documentation effort? - Can I use 'vi' to edit and then merge submit a text file? - How do I know a private from a non-private method? From the '_' prefix? With the questions/comments behind me, I'm willing to take a shot at the 'random' module, trying to choose a simple module to start with. Let me know if you would like me to start on it. Regards, Jim Paul Winkler wrote:
On Sun, Sep 26, 2004 at 03:57:49PM -0400, David Evans wrote:
is there a more complete API reference available, and if not how can i contribute to the update of the curent API to a more complete status?
I've volunteered as editor of the API reference for the next (2.7) edition of the Zope Book. Help would be greatly appreciated.
The version I'm working on is here: http://www.plope.com/Books/2_7Edition/AppendixB.stx
Note the current TODO list here: http://www.plope.com/Books/2_7Edition/AppendixB.stx#1-2
Currently what I'm doing is the first item on that list. A BIG help would be to take responsibility for one or more remaining modules on the list below.
* For all modules, classes, methods, and functions in the reference:
* verify that all names are correct
* see if any non-private methods are missing, and add them
* compare API reference to source docstrings and to the HelpSys .stx files, combine and edit all for completeness and clarity.
* check base classes for things that need documenting - either add the base class to this API ref, or document any non-overridden methods as part of the derived class docs - not sure how best to do this so i'm handling it on a case-by-case basis.
It's a big job, best done one module at a time. So far it takes me about an hour to do one module properly :-( Some modules are done, see DONE below.
The below modules are still to do::
PropertySheet PropertySheets PythonScripts Script SessionInterfaces TransienceInterfaces UserFolder Vocabulary ZCatalog ZSQLMethod ZTUtils math random sequence standard string
Jim has lots of good questions... this is a bit long but I'm keeping this on-list for anyone else interested in the API reference update. On Tue, Sep 28, 2004 at 11:27:07AM -0400, Jim Anderson wrote:
First, thank you for taking on a big responsibility. That is my personal thanks, but I think the entire Zope community owes you a thanks.
you're welcome :) Hope I don't bollox it up too bad :-)
As a bare minimum, I would like to volunteer for one module. Hopefully more, but let's see how it goes. I have considerable experience as a programmer in C, and some in C++ and Python. I have also done my share of documentation in my time and I can write OK, but tend to be boring in my writing (typical engineer).
That's fine (even ideal) for the API reference.
I do have a number of comments/questions about Zope documentation in general:
- As a user, I find the documentation quite useful, but not well structured compared to other documentation projects that I have seen. It leads me to wonder if any one group of people are responsible for planning the overall documentation, or did it just evolve?
I can only really speak about the Zope Book as that's the only docs I'm involved in. The print edition of the Zope Book was planned and executed by Amos Latteier and Michel Pelletier. Since then, it has evolved quite a bit. Chris McDonough is more or less in charge of it, but the structure is not ideal, and it tends to get longer and acquire more redundancy. What happens is that individual people edit a single chapter and Chris gives it some sort of overview, but he doesn't make radical or structural changes to what we send him. Part of the problem is that Zope is inherently hard to write about: in order to fully understand topic A, you need to have some understanding of topic B, which depends on topic C, which depends on a basic understanding of topic A. We try to address this by having "basic" and "advanced" chapters on some topics, but I'm not sure how well this succeeds. Fixing this would be very hard. One would have to read the entire book front to back while keeping in mind a newbie's perspective. I don't know who has time for that :-( I would do it in a second if somebody would pay me :-\
- What comes to mind about the API documentation is my surprise that it is included in the Zope Book in the first place. As a user, I'm much happier using a UNIX manual page or the python html reference information. Has any thought been given to taking the API out of the Zope book and making a stand alone version in XML.
Not XML, but I do have a long-term proposal for the API reference: http://dev.zope.org/Wikis/DevSite/Proposals/SanitizeHelpSysAndAPIReference It attracted some positive comments, but not a groundswell of support. I'm gonna have to push if I want it to happen. It's definitely not going to happen before zope 2.8. Maybe for zope 2.9? This is an even bigger job than just editing the zope book version of the reference. In the interests of expediency, I decided to punt and get something online that people can benefit from asap. (snip)
To be honest, I have not used the HelpSys in Zope and maybe this is what I'm looking for with respect to online help.
It would be if it were anywhere near complete and up to date :-\ I fear it has suffered some bit-rot. Fixing (actually replacing) this is part of the above-mentioned proposal.
- My opinion is that if reference material is more modular, then the documentation will never be up to date - but, it will evolve more quickly, especially since developers can then update documentations in small increments.
True. The only "problem" with my proposal is that it would require zope.org CVS/SVN checkin rights in order to commit changes to the docs, which raises the bar a bit.
- I'm not too experienced in Zope and I'm afraid I will need support in my effort to provide documentation. I think the need for support will diminish as I come up to speed. I wonder how many others out there think of volunteering, but don't because they don't feel they can contribute?
Well, I'm getting more feelers... you're now the third, and one of the others sounded less experienced than yourself. There's plenty a relative newbie can do, even just saying things like "I'm new and from my perspective the XXX example makes no sense because ...".
- I assume there is a group of people to help with the documentation? How big is the group? How is it structured? Is there a group that works on the Zope Book and another that works on the Developers Guide, which I believe needs updating even more than the Zope Book.
There's nothing formal. Generally somebody proposes a project to update something and people jump on board as able. I don't know of any current organized efforts wrt. the dev guide. For the current Zope Book project, see: http://www.plope.com/Books/zb_signup
- Is the documentation kept in CVS or some other repository?
The Zope Book nominally lives online at zope.org. The 2.7 edition is currently at Chris' plope.com site because zope.org was effectively crippled at the time he wanted to start the project. There was a sourceforge project for the ZB a long time ago, but it's years out of date now. I kinda think revision control would be good for the book but I wasn't willing to put in the effort to make that happen, and Chris doesn't seem to mind the current state of affairs, so ... *shrug*
- What is the time frame for reviewing a module? I know you said it takes you an hour to do a good job on a module.
I did 12 on a day off and it took me 12 hours... *shrug* OTOH a good chunk of that was spent dealing with DateTime which is huge.
it will take me 10 times that on my first module because I'll have questions about it. If I commit to have it done in 10 calendar days, is that all right?
That's fine. Sometimes weeks go by without me touching anything. We have no deadline.
- The base class documentation needs to be consistent. In my opinion, all (public) base classes need to be documented individual in the API and reference in derived classes. The last thing you want to do is document base class methods in each derived class (what a mess that would be.)
I know. I'm having a hard time with this. But I don't know if you realize quite the magnitude of what you're suggesting :-) For example, DTMLMethod inherits from something like 25 classes. I've already punted on a few of the modules I've overhauled. The thing is, what we really want to document is not the implementation, but the interface. Ideally we would have IFoo interfaces for everything, as described in the SanitizeHelpSysAndAPIReference wiki. Someday...
- Do I use Zope 2.7.3 source code for the documentation effort?
Yes. Latest stable or beta.
- Can I use 'vi' to edit and then merge submit a text file?
Yep. You can get the "source" (structured text) like so: http://www.plope.com/Books/2_7Edition/AppendixB.stx/document_src Send me a diff and I'll merge it.
- How do I know a private from a non-private method? From the '_' prefix?
Another topic that should be easier than it is :-\ Anything with a _ prefix SHOULD be private, but OTOH some things are fairly widely used, such as ObjectManager._setObject and _getObj. And then there are occasional non-_ methods that are definitely not API, such as AccessControl.User.UserFolder.hasUsers(), which at least is documented as not being part of the API. So you have to make some judgment calls about what is and isn't API. If unsure, ask this list, or maybe zope-dev list.
With the questions/comments behind me, I'm willing to take a shot at the 'random' module, trying to choose a simple module to start with. Let me know if you would like me to start on it.
Hmm, well 'random' is really just the python standard lib module so there's nothing to document really, except make sure the link to python docs is correct. -- Paul Winkler http://www.slinkp.com
Paul Winkler wrote at 2004-9-27 19:57 -0400:
... * check base classes for things that need documenting - either add the base class to this API ref, or document any non-overridden methods as part of the derived class docs - not sure how best to do this so i'm handling it on a case-by-case basis.
Many of the base classes are mostly internal. I think, we do not need a complete reference. It would be Oracle like (this is my synonym for "almost unusable"). IMO it is more valuable to document the most relevant classes (and their most relevant attributes and methods) with typical usage rather than document everything but only superficially. I am still convinced that automatic documentation extraction tools (like "DocFinder") are better than manual documentation -- for everything other than the essential concepts and the overview how things play together.
It's a big job, best done one module at a time.
And keep in mind that it is not a one time job... Every release is likely to change minor details. The more details you document now, the more details need checking for new releases. Do not do it! Document only the most essential classes (and how they fit with one another). Reject any request for a complete documentation. Link to automatic documentation extraction tools ("happydoc", "epidoc", "DocFinder") for people that want more details.... -- Dieter
On Tue, Sep 28, 2004 at 07:21:43PM +0200, Dieter Maurer wrote:
Paul Winkler wrote at 2004-9-27 19:57 -0400:
... * check base classes for things that need documenting - either add the base class to this API ref, or document any non-overridden methods as part of the derived class docs - not sure how best to do this so i'm handling it on a case-by-case basis.
Many of the base classes are mostly internal.
I think, we do not need a complete reference. It would be Oracle like (this is my synonym for "almost unusable").
Thanks for the advice, I really do appreciate it - might keep me from going overboard :-) But while I agree that we don't need "complete", we do need more than what the current API reference provides. To pick a random example, CopySupport is completely absent, and IMO that is not justifiable.
IMO it is more valuable to document the most relevant classes (and their most relevant attributes and methods) with typical usage rather than document everything but only superficially.
I am still convinced that automatic documentation extraction tools (like "DocFinder") are better than manual documentation -- for everything other than the essential concepts and the overview how things play together.
Yes. I don't know if you've seen my long-term proposal: http://dev.zope.org/Wikis/DevSite/Proposals/SanitizeHelpSysAndAPIReference In that shiny sci-fi world, DocFinder would still be a great way to explore the *implementation*, but we would also have clear browsable documentation of the *interfaces*. But this is an even bigger job than twiddling the current API reference by hand, and I want the Zope Book to be better ASAP. Hence my decision to tackle the issue in stages. My plan is that we'll first solve the immediate problem of there being no good reference by getting urgent improvements into the Zope Book first, and then fold the result of this work back in to the source tree in the form of Interface docstrings. Hopefully there will be community input along the way, about what does and does not constitute API.
It's a big job, best done one module at a time.
And keep in mind that it is not a one time job...
Well, if my plan succeeds, it is ;-)
Every release is likely to change minor details. The more details you document now, the more details need checking for new releases.
I think I know what you're saying, but if I take this to its logical conclusion, it means that there should be no documentation at all.
Do not do it! Document only the most essential classes (and how they fit with one another).
Thanks for the sanity check. But as already stated, IMO "the most essential classes" includes a lot that is not currently in the API ref. Base classes are tricky. I hate the "ObjectManagerItem" lie, but I don't want to dive into all of SimpleItem's base classes. I started going down that road and I can see it would be a disaster. Maybe, some of these issues cannot be properly solved without diving into phase 2 of the plan and actually creating something like an ISimpleItem interface. I might have to settle for a Zope Book 2.7 Appendix B that is not as good as I'd like. -- Paul Winkler http://www.slinkp.com
Paul Winkler wrote at 2004-9-29 21:24 -0400:
... Thanks for the advice, I really do appreciate it - might keep me from going overboard :-) But while I agree that we don't need "complete", we do need more than what the current API reference provides. To pick a random example, CopySupport is completely absent, and IMO that is not justifiable.
My favorite view is: We need good overview information: concepts, relations, major building blocks, good examples for the most relevant use cases. These things cannot be derived automatically. Detailed information should be derived automatically only, by documentation extraction tools like "DocFinder", "epydoc" or the Zope3 "ApiDocTool". That they can work well, good source documentation (docstrings) is essential -- and indeed it is not too bad, currently. I already argued with one of the first authors of the Zope Book and the online help content (Michael). I could not convince him. But the current state of affairs (outdated, incomplete, week online help) demonstrates that I was right...
... Yes. I don't know if you've seen my long-term proposal: http://dev.zope.org/Wikis/DevSite/Proposals/SanitizeHelpSysAndAPIReference
I did not read the proposal but followed the occurrences in the mailing list. Personally, I would go this route and would not try to complete the API reference in the Zope Book. This does not mean, that no work whatsoever should go into the API reference: if something *really* important is missing, it should be added. But, there are more important tasks than making it 100 per cent complete...
In that shiny sci-fi world, DocFinder would still be a great way to explore the *implementation*, but we would also have clear browsable documentation of the *interfaces*. But this is an even bigger job than twiddling the current API reference by hand...
Are you sure? An interface is nothing more than a collection of methods (and maybe attributes). This meta information can be provided by (attribute) annotations directly in the source. This is much less work than documenting the interface relation in e.g. a piece of documentation. An automatic extraction tool can look at these meta information attributes and present the available methods (and attributes) accordingly. You look at the result and maybe improve a few method docstrings. This will help not only the documentation but source maintenance, too. That's it. Hopefully, future software evolution will follow your example (and extend the meta information attributes accordingly) and you will always have up to date reference information -- without lots of manual work for any new release...
... Hence my decision to tackle the issue in stages. My plan is that we'll first solve the immediate problem of there being no good reference by getting urgent improvements into the Zope Book first, and then fold the result of this work back in to the source tree in the form of Interface docstrings.
That's what I like to call the power of handling person. Were I the handling person, I surely would proceed the other way round :-)
... I think I know what you're saying, but if I take this to its logical conclusion, it means that there should be no documentation at all.
No documentation that can be extracted. Yes indeed! You still need the big picture: principles, paradigms, concepts, how fits everything together. Take the Java documentation as an example: 90 per cent is automatically extracted directly from the source via JavaDoc. -- Dieter
On Thu, Sep 30, 2004 at 09:22:47PM +0200, Dieter Maurer wrote: (snip)
I already argued with one of the first authors of the Zope Book and the online help content (Michael). I could not convince him. But the current state of affairs (outdated, incomplete, week online help) demonstrates that I was right...
Well, there is one good reason for the BackTalk version of the API reference - namely, the backtalk feature. Users sometimes have good questions that deserve to be addressed, and as an occasional Zope Book editor, I've found BackTalk an excellent way to gather these. (As a Zope Book *reader*, I find them mostly annoyances... don't know how to reconcile these two issues.)
Yes. I don't know if you've seen my long-term proposal: http://dev.zope.org/Wikis/DevSite/Proposals/SanitizeHelpSysAndAPIReference
I did not read the proposal but followed the occurrences in the mailing list.
Personally, I would go this route and would not try to complete the API reference in the Zope Book.
This does not mean, that no work whatsoever should go into the API reference: if something *really* important is missing, it should be added. But, there are more important tasks than making it 100 per cent complete...
Agreed. I'm not aiming for 100. But I'm aiming for significant improvement over the current one which has become really bad IMO.
In that shiny sci-fi world, DocFinder would still be a great way to explore the *implementation*, but we would also have clear browsable documentation of the *interfaces*. But this is an even bigger job than twiddling the current API reference by hand...
Are you sure?
Well, no. But it requires adding a whole lot of files to the Zope source code since many things do'nt have interfaces, and touching the classes to assert that they implement those interfaces, and adding tests that validate that they implement those interfaces. To me that sounds like a big job and probably the results will not be seen by anyone until zope 2.9. Compare this to the revision of the online API reference, which in my estimate is about half finished and can already be read by people today at plope.com.
That's what I like to call the power of handling person. Were I the handling person, I surely would proceed the other way round :-)
:) Thanks for the input. -- Paul Winkler http://www.slinkp.com
On Thu, 30 Sep 2004 17:28:27 -0400 Paul Winkler <pw_lists@slinkp.com> wrote about Re: [Zope] general API question: -------------------------------------------- | On Thu, Sep 30, 2004 at 09:22:47PM +0200, Dieter Maurer wrote: | (snip) | > I already argued with one of the first authors of the Zope Book | > and the online help content (Michael). | > I could not convince him. But the current state of affairs | > (outdated, incomplete, week online help) demonstrates that I was | > right... | | Well, there is one good reason for the BackTalk version of | the API reference - namely, the backtalk feature. Indeed. | Users sometimes have good questions that deserve to be addressed, | and as an occasional Zope Book editor, I've found BackTalk an | excellent way to gather these. | (As a Zope Book *reader*, I find them mostly annoyances... | don't know how to reconcile these two issues.) I suggest keeping the BackTalk version online, and periodically auto-generating a talkback-stripped version available for download. | > Personally, I would go this route and would not try to complete | > the API reference in the Zope Book. Perhaps, adding to the donwload bundle an epydoc-run over Zope srcs would be a plus. Why not keeping both versions on-line ? To foster people going through the 'commentable' one ;o) best regards, Senra
Paul and Dieter, Combined, I feel you two have struck what I consider the most important points. In his original response to me, Paul hit the nail on the head when he said that the interface needs to be documented, meaning the public interface, of course. Quite simply, if a class or method is in the public interface, it should be documented. At this point, I'm not sure who decides if a method or class is public or not, but I'll learn as I go forward. I agree with Dieter that the API documentation should be generated automatically. Jim Paul Winkler wrote:
On Tue, Sep 28, 2004 at 07:21:43PM +0200, Dieter Maurer wrote:
Paul Winkler wrote at 2004-9-27 19:57 -0400:
... * check base classes for things that need documenting - either add the base class to this API ref, or document any non-overridden methods as part of the derived class docs - not sure how best to do this so i'm handling it on a case-by-case basis.
Many of the base classes are mostly internal.
I think, we do not need a complete reference. It would be Oracle like (this is my synonym for "almost unusable").
Thanks for the advice, I really do appreciate it - might keep me from going overboard :-) But while I agree that we don't need "complete", we do need more than what the current API reference provides. To pick a random example, CopySupport is completely absent, and IMO that is not justifiable.
IMO it is more valuable to document the most relevant classes (and their most relevant attributes and methods) with typical usage rather than document everything but only superficially.
I am still convinced that automatic documentation extraction tools (like "DocFinder") are better than manual documentation -- for everything other than the essential concepts and the overview how things play together.
Yes. I don't know if you've seen my long-term proposal: http://dev.zope.org/Wikis/DevSite/Proposals/SanitizeHelpSysAndAPIReference
In that shiny sci-fi world, DocFinder would still be a great way to explore the *implementation*, but we would also have clear browsable documentation of the *interfaces*. But this is an even bigger job than twiddling the current API reference by hand, and I want the Zope Book to be better ASAP. Hence my decision to tackle the issue in stages. My plan is that we'll first solve the immediate problem of there being no good reference by getting urgent improvements into the Zope Book first, and then fold the result of this work back in to the source tree in the form of Interface docstrings.
Hopefully there will be community input along the way, about what does and does not constitute API.
It's a big job, best done one module at a time.
And keep in mind that it is not a one time job...
Well, if my plan succeeds, it is ;-)
Every release is likely to change minor details. The more details you document now, the more details need checking for new releases.
I think I know what you're saying, but if I take this to its logical conclusion, it means that there should be no documentation at all.
Do not do it! Document only the most essential classes (and how they fit with one another).
Thanks for the sanity check. But as already stated, IMO "the most essential classes" includes a lot that is not currently in the API ref.
Base classes are tricky. I hate the "ObjectManagerItem" lie, but I don't want to dive into all of SimpleItem's base classes. I started going down that road and I can see it would be a disaster.
Maybe, some of these issues cannot be properly solved without diving into phase 2 of the plan and actually creating something like an ISimpleItem interface. I might have to settle for a Zope Book 2.7 Appendix B that is not as good as I'd like.
Jim Anderson wrote at 2004-9-30 20:11 -0400:
... Quite simply, if a class or method is in the public interface, it should be documented. At this point, I'm not sure who decides if a method or class is public or not, but I'll learn as I go forward.
"DocFinder" (for example) distinguished 3 levels of "publicness": * public for through the Web access * public for scripting use * public for developers One might want to differentiate the "public for developers" further: "public" for standard class use (i.e. what e.g. C++/Java calls "public") "public" for deriving classes (what C++ calls "protected") and really private (what C++ calls "private"). Depending on the level you are working, other interfaces become relevant. I think, we are currently mainly speaking about "public for standard use". -- Dieter
FYI public API docs are linked at http://zopewiki.org/api . epydoc seems to be the best tool for automatically documenting Zope, but it's difficult to get it to run (over all of zope) and occasionally the generated pages seem to be missing information. See discussion at http://zopewiki.org/epydoc . We should discover and document a reliable procedure for generating complete zope epydocs, any help welcome. zpydoc is less well-organized to read but wonderfully quick and easy to set up. The pages it generates also sometimes miss information, and on my server certain links trigger a python crashing bug.
On Tue, 05 Oct 2004 14:24:44 -0700, Simon Michael <simon@joyful.com> wrote:
epydoc seems to be the best tool for automatically documenting Zope, but it's difficult to get it to run (over all of zope) and occasionally the generated pages seem to be missing information. See discussion at http://zopewiki.org/epydoc . We should discover and document a reliable procedure for generating complete zope epydocs, any help welcome.
I'd really like to see more use of Epydoc, especially once we've got a nice recipe for running it on a large set of packages. It's actually quite nice when all you want to look at is the documentation -- much better than just browsing the code directly, and the ReST support is good. -Fred -- Fred L. Drake, Jr. <fdrake at gmail.com> Zope Corporation
participants (8)
-
David Evans -
Dieter Maurer -
Fred Drake -
Jim Anderson -
Jonathan Hobbs -
Paul Winkler -
Rodrigo Senra -
Simon Michael