[Zope-dev] New Help System in 2.2

[Paul Everitt]

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 )