New Help System in 2.2
Michel, I was just browsing the help system and can I just say it is terrfic. The .py files especially. Not that python isn't that easy to read, but having the ZQR type stuff handy online is a huge win. Is that stuff updated fro mthe source on the fly? Greatfully, Jason Spisak CIO HireTechs.com 6151 West Century Boulevard Suite 900 Los Angeles, CA 90045 P. 310.665.3444 F. 310.665.3544 Under US Code Title 47, Sec.227(b)(1)(C), Sec.227(a)(2)(B) This email address may not be added to any commercial mail list with out my permission. Violation of my privacy with advertising or SPAM will result in a suit for a MINIMUM of $500 damages/incident, $1500 for repeats.
Jason Spisak wrote:
I was just browsing the help system and can I just say it is terrfic. The .py files especially. Not that python isn't that easy to read, but having the ZQR type stuff handy online is a huge win. Is that stuff updated from the source on the fly?
Almost. It's actually written in separate files that mirror the structure of the real source. And I'd like to bring up the point that I wonder why it is written that way. Wouldn't it make more sense to self-document the source? If the issue is that some methods shouldn't be callable from a URL, there are better solutions to that problem (this is written to DC mainly): 1) Enahnce the permissions system to include "Accessible via HTTP", "Accessible via FTP", etc. 2) Use an underscore as the first character of a docstring to indicate a non-URL-callable method. Shane
Shane Hathaway wrote:
1) Enahnce the permissions system to include "Accessible via HTTP", "Accessible via FTP", etc.
Add to that 'execute in DTML method' ( + python methods & perl methods;-) and you've got what I've been asking for for so long I've atoped trying :( This would prevent the nasty ability to do things like: http://www.zope.org/standard_html_footer This should not be accessible through HTTP, but should be through FTP and DTML... cheers, Chris
Shane Hathaway writes:
Jason Spisak wrote:
I was just browsing the help system and can I just say it is terrfic. The .py files especially. Not that python isn't that easy to read, but having the ZQR type stuff handy online is a huge win. Is that stuff updated from the source on the fly?
Almost. It's actually written in separate files that mirror the structure of the real source. And I'd like to bring up the point that I wonder why it is written that way. Wouldn't it make more sense to self-document the source?
If the issue is that some methods shouldn't be callable from a URL, there are better solutions to that problem (this is written to DC mainly):
Is this the reason that it's not pulling the docs from the source? That's not a good idea. With all the effort that Michel put in to work around not documenting in the source, he could have fixed it so that it pulled the docs from the source on the fly without effecting the URL access.
1) Enahnce the permissions system to include "Accessible via HTTP", "Accessible via FTP", etc. 2) Use an underscore as the first character of a docstring to indicate a non-URL-callable method.
I just looked at it and that seems like doing work twice. Why not just document your source? Wonderingly, Jason Spisak CIO HireTechs.com 6151 West Century Boulevard Suite 900 Los Angeles, CA 90045 P. 310.665.3444 F. 310.665.3544 Under US Code Title 47, Sec.227(b)(1)(C), Sec.227(a)(2)(B) This email address may not be added to any commercial mail list with out my permission. Violation of my privacy with advertising or SPAM will result in a suit for a MINIMUM of $500 damages/incident, $1500 for repeats.
At 09:09 PM 5/30/00 +0000, Jason Spisak wrote:
Shane Hathaway writes:
Jason Spisak wrote:
I was just browsing the help system and can I just say it is terrfic. The .py files especially. Not that python isn't that easy to read, but having the ZQR type stuff handy online is a huge win. Is that stuff updated from the source on the fly?
Almost. It's actually written in separate files that mirror the structure of the real source. And I'd like to bring up the point that I wonder why it is written that way. Wouldn't it make more sense to self-document the source?
If the issue is that some methods shouldn't be callable from a URL, there are better solutions to that problem (this is written to DC mainly):
Is this the reason that it's not pulling the docs from the source? That's not a good idea. With all the effort that Michel put in to work around not documenting in the source, he could have fixed it so that it pulled the docs from the source on the fly without effecting the URL access.
1) Enahnce the permissions system to include "Accessible via HTTP", "Accessible via FTP", etc. 2) Use an underscore as the first character of a docstring to indicate a non-URL-callable method.
I just looked at it and that seems like doing work twice. Why not just document your source?
I just talked to Amos and Michel last Friday about that and they researched for a long time, whether it would be better to document the source or to have different files. They both decided it is the best to have the documentation separately. I believe that they looked at the issue from all angles and had good reasons, why they went with the current way. Furthermore, the help system will become even more than just the screen help. The .py files you see, are just the start of the new API documentation. Furthermore, we will include a new DTML reference soon. Do you know about anything else, that should be included? Regards, Stephan -- Stephan Richter CBU - Physics and Chemistry Web2k - Web Design/Development & Technical Project Management
Stephan Richter writes:
At 09:09 PM 5/30/00 +0000, Jason Spisak wrote:
Shane Hathaway writes:
Jason Spisak wrote:
I was just browsing the help system and can I just say it is terrfic. The .py files especially. Not that python isn't that easy to read, but having the ZQR type stuff handy online is a huge win. Is that stuff updated from the source on the fly?
Almost. It's actually written in separate files that mirror the structure of the real source. And I'd like to bring up the point that I wonder why it is written that way. Wouldn't it make more sense to self-document the source?
If the issue is that some methods shouldn't be callable from a URL, there are better solutions to that problem (this is written to DC mainly):
Is this the reason that it's not pulling the docs from the source? That's not a good idea. With all the effort that Michel put in to work around not documenting in the source, he could have fixed it so that it pulled the docs from the source on the fly without effecting the URL access.
1) Enahnce the permissions system to include "Accessible via HTTP", "Accessible via FTP", etc. 2) Use an underscore as the first character of a docstring to indicate a non-URL-callable method.
I just looked at it and that seems like doing work twice. Why not just document your source?
I just talked to Amos and Michel last Friday about that and they researched for a long time, whether it would be better to document the source or to have different files. They both decided it is the best to have the documentation separately. I believe that they looked at the issue from all angles and had good reasons, why they went with the current way.
I trust them implicitly. I'm sure that my gut reaction was probably the same one they had, but after careful thought they found a better solution.
Furthermore, the help system will become even more than just the screen help. The .py files you see, are just the start of the new API documentation.
Oooo.
Furthermore, we will include a new DTML reference soon. Do you know about anything else, that should be included?
Well if you really want to make it hot, the examples that are in there can keep coming. Web links might not be out of order either. The only problem is that there is no difinitive Zope online docs to link to, to get the most recent info. But when there is, it would be nice to include. Thanks, Jason Spisak CIO HireTechs.com 6151 West Century Boulevard Suite 900 Los Angeles, CA 90045 P. 310.665.3444 F. 310.665.3544 Under US Code Title 47, Sec.227(b)(1)(C), Sec.227(a)(2)(B) This email address may not be added to any commercial mail list with out my permission. Violation of my privacy with advertising or SPAM will result in a suit for a MINIMUM of $500 damages/incident, $1500 for repeats.
I can add a bit more background on the decision to have the API docs not rendered from the source. First, Zope used to have an online help system that inspected the source and rendered documenation on the fly. Very nice indeed. But we yanked it. Why? The most primary reason is philosophical, a la Jim Fulton. Jim believes strongly in the idea that interfaces are _not_ connected to implementation: http://www.zope.org/Members/jim/PythonInterfaces/Summary Thus, the new system is patterned after this philosophy. The interface is the contract that one or more implementations should live up to. Right now we aren't doing much of that which Jim described. The interface is just a documentation artifact. But it is philosophically consistent with what we'd ultimately like to do. --Paul Stephan Richter wrote:
At 09:09 PM 5/30/00 +0000, Jason Spisak wrote:
Shane Hathaway writes:
Jason Spisak wrote:
I was just browsing the help system and can I just say it is terrfic. The .py files especially. Not that python isn't that easy to read, but having the ZQR type stuff handy online is a huge win. Is that stuff updated from the source on the fly?
Almost. It's actually written in separate files that mirror the structure of the real source. And I'd like to bring up the point that I wonder why it is written that way. Wouldn't it make more sense to self-document the source?
If the issue is that some methods shouldn't be callable from a URL, there are better solutions to that problem (this is written to DC mainly):
Is this the reason that it's not pulling the docs from the source? That's not a good idea. With all the effort that Michel put in to work around not documenting in the source, he could have fixed it so that it pulled the docs from the source on the fly without effecting the URL access.
1) Enahnce the permissions system to include "Accessible via HTTP", "Accessible via FTP", etc. 2) Use an underscore as the first character of a docstring to indicate a non-URL-callable method.
I just looked at it and that seems like doing work twice. Why not just document your source?
I just talked to Amos and Michel last Friday about that and they researched for a long time, whether it would be better to document the source or to have different files. They both decided it is the best to have the documentation separately. I believe that they looked at the issue from all angles and had good reasons, why they went with the current way. Furthermore, the help system will become even more than just the screen help. The .py files you see, are just the start of the new API documentation. Furthermore, we will include a new DTML reference soon. Do you know about anything else, that should be included?
Regards, Stephan -- Stephan Richter CBU - Physics and Chemistry Web2k - Web Design/Development & Technical Project Management
_______________________________________________ Zope-Dev maillist - Zope-Dev@zope.org http://lists.zope.org/mailman/listinfo/zope-dev ** No cross posts or HTML encoding! ** (Related lists - http://lists.zope.org/mailman/listinfo/zope-announce http://lists.zope.org/mailman/listinfo/zope )
Paul Everitt wrote:
I can add a bit more background on the decision to have the API docs not rendered from the source.
First, Zope used to have an online help system that inspected the source and rendered documenation on the fly. Very nice indeed. But we yanked it.
Why? The most primary reason is philosophical, a la Jim Fulton. Jim believes strongly in the idea that interfaces are _not_ connected to implementation:
I think it's more important that interfaces should be explicit, not implicit. They should be connected to the implementation all right; just not *implicit* in the implementation. It would be very nice eventually if the implementation could explicitly check whether an object conforms to a certain interface though, and as far as I'm aware this is also what Jim's saying.
Thus, the new system is patterned after this philosophy. The interface is the contract that one or more implementations should live up to.
Right now we aren't doing much of that which Jim described. The interface is just a documentation artifact. But it is philosophically consistent with what we'd ultimately like to do.
Ultimately I'd like to be able to say in the Zope sources loud and clearly 'this object conforms to THIS interface'. And then you'd have somewhere else in the Zope sources the interface definition (which is also just in Python source), which has documentation associated with it, probably as a docstring in the code, though potentially also with a reference to some file in another format. And then you should generate the API documentation from that. I'd also say that actually active source-wise implementation of this interface philosophy is quite important for the long term viability of the Zope sources. Otherwise the documentation (even of interfaces) will always end up being behind the actual Zope sources, making it worth a lot less. Regards, Martijn
Martijn Faassen writes:
And then you should generate the API documentation from that. I'd also say that actually active source-wise implementation of this interface philosophy is quite important for the long term viability of the Zope sources. Otherwise the documentation (even of interfaces) will always end up being behind the actual Zope sources, making it worth a lot less.
I agree with this last assertion. Jason Spisak CIO HireTechs.com 6151 West Century Boulevard Suite 900 Los Angeles, CA 90045 P. 310.665.3444 F. 310.665.3544 Under US Code Title 47, Sec.227(b)(1)(C), Sec.227(a)(2)(B) This email address may not be added to any commercial mail list with out my permission. Violation of my privacy with advertising or SPAM will result in a suit for a MINIMUM of $500 damages/incident, $1500 for repeats.
I too agree the new help system looks nice. I was considering at one point jumping up and writing a documentation system for Python/Zope. Unfortunately my notes, not many, are at work. But some things I had in mind were based on something like JavaDoc. I am not a Java expert and have not really used JavaDoc much but have seen some of its documentation. I was thinking it would be nice to have a parser which could extract documentation from source to create external documentation files which could be generated into multiple formats, html, xml, etc. I would have needed to create a documentation format which could be used in source but extracted. I was not going to use docstrings as they are intended for a different purpose and are compiled into the bytecode. I was thinking that the parser could run over a module and extract functions, methods, variables and properties, etc. and create a stub framework on a form. A documenter could then edit documentation for any or all of the methods, save and it would be inserted appropriately into source. I thought it would also be nice if the documentation tree would also parallel the source tree and have a corresponding colorized html rendering of the module for browsing. This way one could jump from documentation to source at will. I was basically making idea notes. I was going to look at the current doc generating and py2html tools available first. Then Starship went down and I couldn't access them. :( I also wanted to see what the DC team was doing. I think it would be nice to see some ideas and processes for what and how Amos and Michel are doing with the documentation and how the community can help. Just some thoughts. Jimmie Houchin Jason Spisak wrote:
Shane Hathaway writes:
Jason Spisak wrote:
I was just browsing the help system and can I just say it is terrfic. The .py files especially. Not that python isn't that easy to read, but having the ZQR type stuff handy online is a huge win. Is that stuff updated from the source on the fly?
Almost. It's actually written in separate files that mirror the structure of the real source. And I'd like to bring up the point that I wonder why it is written that way. Wouldn't it make more sense to self-document the source?
If the issue is that some methods shouldn't be callable from a URL, there are better solutions to that problem (this is written to DC mainly):
Is this the reason that it's not pulling the docs from the source? That's not a good idea. With all the effort that Michel put in to work around not documenting in the source, he could have fixed it so that it pulled the docs from the source on the fly without effecting the URL access.
1) Enahnce the permissions system to include "Accessible via HTTP", "Accessible via FTP", etc. 2) Use an underscore as the first character of a docstring to indicate a non-URL-callable method.
I just looked at it and that seems like doing work twice. Why not just document your source?
Wonderingly,
Jason Spisak CIO HireTechs.com 6151 West Century Boulevard Suite 900 Los Angeles, CA 90045 P. 310.665.3444 F. 310.665.3544
Under US Code Title 47, Sec.227(b)(1)(C), Sec.227(a)(2)(B) This email address may not be added to any commercial mail list with out my permission. Violation of my privacy with advertising or SPAM will result in a suit for a MINIMUM of $500 damages/incident, $1500 for repeats.
_______________________________________________ Zope-Dev maillist - Zope-Dev@zope.org http://lists.zope.org/mailman/listinfo/zope-dev ** No cross posts or HTML encoding! ** (Related lists - http://lists.zope.org/mailman/listinfo/zope-announce http://lists.zope.org/mailman/listinfo/zope )
Jimmie Houchin writes:
I was considering at one point jumping up and writing a documentation system for Python/Zope. Unfortunately my notes, not many, are at work. But some things I had in mind were based on something like JavaDoc. I am not a Java expert and have not really used JavaDoc much but have seen some of its documentation.
I was thinking it would be nice to have a parser which could extract documentation from source to create external documentation files which could be generated into multiple formats, html, xml, etc. I would have needed to create a documentation format which could be used in source but extracted. I was not going to use docstrings as they are intended for a different purpose and are compiled into the bytecode.
You might want to take a look at the bottom of http://www.lfw.org/python/...
"Dan L. Pierson" wrote:
You might want to take a look at the bottom of http://www.lfw.org/python/...
He finally released it! I've been waiting for this since IPC8. -- Itamar S.T. itamar@maxnm.com "It don't get thingier than that!"
participants (9)
-
Chris Withers -
Dan L. Pierson -
Itamar Shtull-Trauring -
Jason Spisak -
Jimmie Houchin -
Martijn Faassen -
Paul Everitt -
Shane Hathaway -
Stephan Richter