[Zope3-Users] Zope 3 API documentation needs a new strategy
One of the first questions anyone needs answered when studying a new framework is Where is the canonical reference for the API?. If you google for zope 3 api documentation the first link is Stephan Richter's mail of Jan/2004 announcing API doc. In it, there is the link: http://localhost:8080/++apidoc++ However, that URL is not active by default, and it takes some research discover how to make it work. The second link returned by Google is this: http://wiki.zope.org/zope3/Documentation Here we find vague references to a certain API Doc Tool, but no explanation of how to enable it and access it (OK, that is a Wiki, so it's easy to fix; I'll start the APIDocTool page). The remaining links returned by Google are even less helpful, and on page 2 we get a link to Shane Hathaway's post titled Zope 3 Frustration... Everyone expects the API documentation for a framework to be highly visibile in it's main web site. OK, I understand Zope 3 is undergoing a radical reorganization right now, which is a further push to descentralization, making the idea of locally generated API documentation even more attractive. But I think we *also* need the API published on Zope.org, for a few advantages that the apidoc tool will never be able to give us: - we need to be able to use Google to search the API documentation (even if the apidoc search worked perfectly, which it doesn't) - we need to be able to collaborate with comments and examples to the docs; The second point is really crucial. Just take a look at this page, *please*: http://www.php.net/manual/en/ref.classobj.php Last year I had to do a project in PHP, and again and again the answers I was looking for were in the contributed comments and examples, even though their documentation is very compreehensive. The same amazing user participation can be seen in all 23 languages (!) in which the PHP API is documented. Contributing to Zope 3 docs must be made *much* easier than being a Zope 3 committer. Cheers, Luciano ___ Zope3-users mailing list Zope3-users@zope.org http://mail.zope.org/mailman/listinfo/zope3-users
Re: Vedr. [Zope3-Users] Zope 3 API documentation needs a new strategy
On 7/18/07, Benji York [EMAIL PROTECTED] wrote: Does http://wiki.zope.org/zope3/Documentation help? Not really. Before yesterday, there was no explanation about how to access apidoc (I put that in the linked page APIDocTool yesterday). The apidoc tool itself is limited. For debugging purposes, it might be useful that the search is limited to registered interfaces. But while reading about Zope 3 I wanted to check on IComponentArchitecture but the search could not find it. I had to use grep to find it and learn the path that I could use to browse to it in the apidoc: http://localhost:8099/++apidoc++/Interface/zope.component.interfaces.IComponentArchitecture/index.html And finally, the wiki Documentation page does not mention the abundant README.txt files scattered all over the source tree where the real documentation exists. Cheers, Luciano PS. BTW, I'd like to mention that besides the people who replied in the list, I got pvt replies of people saying that they feel the same way as I do about the current docs. ___ Zope3-users mailing list Zope3-users@zope.org http://mail.zope.org/mailman/listinfo/zope3-users
Re: [Zope3-Users] I need an advice
On 9/12/07, Santiago Videla [EMAIL PROTECTED] wrote: the question is: what do you think: should I use Zope3 or Plone3 ? Santiago, take a look at Grok: http://grok.zope.org Grok is Zope 3 with an API which makes the simple tasks simple. And as the complexity of the task increases, the entire Zope 3 API is at hand, without limitations. Cheers, Luciano ___ Zope3-users mailing list Zope3-users@zope.org http://mail.zope.org/mailman/listinfo/zope3-users
Re: [Zope3-Users] Zope 3 API documentation needs a new strategy
On Nov 12, 2007 2:49 AM, Stephan Richter [EMAIL PROTECTED] wrote: On Tuesday 17 July 2007, Luciano Ramalho wrote: Everyone expects the API documentation for a framework to be highly visibile in it's main web site. It now is, thanks to some people finally finishing the static apidoc. http://apidoc.zope.org Hooray!!! Thanks and congrats to all involved! But I think we *also* need the API published on Zope.org, for a few advantages that the apidoc tool will never be able to give us: - we need to be able to use Google to search the API documentation (even if the apidoc search worked perfectly, which it doesn't) How does a published APIDOC version not fulfill this requirement? Who said it does not? My main point was that Google could not index the apidocs installed in our development boxes. Now it finally can, and that is great news! - we need to be able to collaborate with comments and examples to the docs; I do not think that an API reference should contain comments and examples. That's the role of other documentation. In fact, I believe reference documentation should *always* be autogenerated, otherwise information-rot is guaranteed. Information rot is a problem, granted. But do not underestimate the value of content reflecting the perspective of people who use the framework even though they are not core developers of it. The second point is really crucial. Just take a look at this page, *please*: http://www.php.net/manual/en/ref.classobj.php A programming language is always much easier to document than a large framework, especially one that is dynamically configured. Granted, but we are not afraid of challenges! Contributing to Zope 3 docs must be made *much* easier than being a Zope 3 committer. Well, you can always contribute to the Wiki, start your own page, or do whatever. Of course those options are always available, but they totally miss my point. My point is that, so far, the documentation of Zope 3 has been written by the framework developers for the framework developers. That is evident from the way it has been written, organized and (not) published until now. But a successful framework has many more programmers who use it than those who help develop it, and the documentation should be open to contributions from the entire community of users. However, just complaining about it will not improve the situation. I am not just complaining. I am having a public debate with you and anyone else who cares to join about ways to make the Zope 3 API more accessible to people outside of the committers group. I see value in this, and I am happy to note that you do too, otherwise you would not have resurrected this thread which I started fours months ago. (Since then I've also started contributing to the Grok project with examples, docs and code.) Don't get me wrong, Stephan: the dynamic APIDOC tool is fantastic, you deserve many thanks from the community for it and for all of your contributions to Zope 3 over the years. Publishing the static APIDOC was a great step forward. At the same time, Grok and Plone 3 are bringing lots of new programmers to the Zope 3 world. I am sure the increased visibility and audience will be of great benefit to the Zope 3 docs, if we make it easier for people contribute. Cheers, Luciano ___ Zope3-users mailing list Zope3-users@zope.org http://mail.zope.org/mailman/listinfo/zope3-users
Re: [Zope3-Users] Principally annotating InternalPrincipals at creation time
Hello, John and Zope 3 gurus, I wonder if the question reproduced below was answered somewhere. I'm struggling with the same issue: I am using a PrincipalFolder to store InternalPrincipal instances, but I want to annotate them but can't figure out how. Also, I wonder why the IInternalPrincipal does not extend IPrincipal. I may be wrong, but I get the feeling that the name principal has been abused to describe two different things in the API: usually a principal is non-persistent object which represents an user during a request, but in the case of the PrincipalFolder, the InternalPrincipal are not those same principals, but rather persistent objects which represent an account that allows a principal of the first kind to log in. Cheers and a happy 2008 to all! -- Luciano On Aug 11, 2007 11:56 PM, John Maddison [EMAIL PROTECTED] wrote: Hi all, I'm using a PrincipalFolder to store users who have signed up to a site, and during signup I'd like to ask them for some more information (email address, etc) and store it in a principal annotation. However, PrincipalFolders use IInternalPrincipals, which do not appear to be easily converted to annotatable IPrincipals until after a user has logged in, so I'm at a bit of a loss as to how I can store this metadata at signup. I guess I could log the user in and then ask for the information on the next page, or store the information in the session until the user is logged in and the IPrincipal easily available, but I get the feeling I'm missing something simple - this seems like something people would often want. So, are people doing this, and if so, how? Thanks! ___ Zope3-users mailing list Zope3-users@zope.org http://mail.zope.org/mailman/listinfo/zope3-users ___ Zope3-users mailing list Zope3-users@zope.org http://mail.zope.org/mailman/listinfo/zope3-users
Re: [Zope3-Users] Principally annotating InternalPrincipals at creation time
On Jan 1, 2008 10:05 PM, Luciano Ramalho [EMAIL PROTECTED] wrote: I wonder if the question reproduced below was answered somewhere. I'm struggling with the same issue: I am using a PrincipalFolder to store InternalPrincipal instances, but I want to annotate them but can't figure out how. I ended up declaring that InternalPrincipal implements the marker interface IAttributeAnnotatable, and that allowed me to annotate to the InternalPrincipal instances. It works because InternalPrincipal instances reside in the ZODB, but I wonder if it's a good idea. If it's not, then I'd love to see a recipe on how to use the PrincipalAnnotation machinery with InternalPrincipal instances. Also, I wonder why the IInternalPrincipal does not extend IPrincipal. I may be wrong, but I get the feeling that the name principal has been abused to describe two different things in the API: usually a principal is non-persistent object which represents an user during a request, but in the case of the PrincipalFolder, the InternalPrincipal are not those same principals, but rather persistent objects which represent an account that allows a principal of the first kind to log in. I'm still wondering about this part... Cheers, Luciano ___ Zope3-users mailing list Zope3-users@zope.org http://mail.zope.org/mailman/listinfo/zope3-users